HTML Tidy  5.4.0
The HTACG Tidy HTML Project
language.h
Go to the documentation of this file.
1 #ifndef language_h
2 #define language_h
3 /*
4  * language.h
5  * Localization support for HTML Tidy.
6  * This header provides the public (within libtidy) interface
7  * to basic localization support. To add your own localization
8  * create a new `language_xx.h` file and add it to the struct
9  * in `language.c`.
10  *
11  * (c) 2015 HTACG
12  * See tidy.h and access.h for the copyright notice.
13  *
14  * Created by Jim Derry on 11/28/15.
15  */
16 
17 #include "tidyplatform.h"
18 
19 
20 /** @name Exposed Data Structures */
21 /** @{ */
22 
23 /**
24  * Describes a record for a localization string.
25  * - key must correspond with one of Tidy's enums (see `tidyMessageTypes`
26  * below)
27  * - pluralForm corresponds to gettext plural forms case (not singularity).
28  * Most entries should be case 0, representing the single case.:
29  * https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html
30  */
31 typedef struct languageDictionaryEntry {
36 
37 
38 /**
39  * For now we'll just use an array to hold all of the dictionary
40  * entries. In the future we can convert this to a hash structure
41  * which will make looking up strings faster.
42  */
44 
45 
46 /**
47  * Finally, a complete language definition. The item `pluralForm`
48  * is a function pointer that will provide the correct plural
49  * form given the value `n`. The actual function is present in
50  * each language header and is language dependent.
51  */
52 typedef struct languageDefinition {
56 
57 
58 /**
59  * The function getNextWindowsLanguage() returns pointers to this type;
60  * it gives LibTidy implementors the ability to determine how Windows
61  * locale names are mapped to POSIX language codes.
62  */
63 typedef struct tidyLocaleMapItem {
67 
68 
69 /**
70  * The function getNextErrorCode() returns pointers to this type; it gives
71  * LibTidy implementors the ability to know what errors can be returned
72  * via `TidyReportFilter3`.
73  * Provides the mapping for LibTidy users to map between an opaque key
74  * and an error message value. See `tidyErrorFilterKeys[]` in `language.c`.
75  * The `key` string is guaranteed by the API (unless deleted entirely). The
76  * `value` is suitable for use in looking up Tidy's strings, but its value
77  * is not guaranteed between releases.
78  */
79 typedef struct tidyErrorFilterKeyItem {
81  int value;
83 
84 
85 /**
86  * Defines all of the possible dictionary keys.
87  * The starting value is arbitrary but must prevent overlaps
88  * with other enums that are used for retrieving strings. The
89  * comprehensive list of enums for which we provides strings
90  * is as follows:
91  * - `tidyMessageTypes` in this file, start == 4096.
92  * - `tidyErrorCodes` from `message.h`, start == 200.
93  * - `accessErrorCodes` from `access.h`, start == CODES_TIDY_ERROR_LAST+1.
94  * - `tidyMessagesMisc` from `message.h`, start == 2048.
95  * - `TidyOptionId` from `tidyEnum.h`, start == 0 (important!).
96  * - `TidyReportLevelKeys` from `tidyEnum.h`, start == 600.
97  * - ...
98  * You should never count on the value of a label being
99  * constant. Accordingly feel free to arrange new enum
100  * values in the most appropriate grouping below.
101  */
102 typedef enum
103 {
104  /* This MUST be present and first. */
106 
107  /* Specify the code for this language. */
109 
110  /* Localization test strings. */
113 
114  /* Strings for the console application. */
200 
201  /* This MUST be present and last. */
204 
205 
206 /**
207  * LibTidy users may want to use `TidyReportFilter3` to enable their own
208  * localization lookup features. Because Tidy's errors codes are enums the
209  * specific values can change over time. This function returns a string
210  * representing the enum value name that can be used as a lookup key
211  * independent of changing string values (TidyReportFiler2 is vulnerable
212  * to changing strings). `TidyReportFilter3` will return this general
213  * string as the error message indicator.
214  */
216 
217 
218 /** @} */
219 /** @name Localization Related Functions */
220 /** @{ */
221 
222 
223 /**
224  ** Determines the current locale without affecting the C locale.
225  ** Tidy has always used the default C locale, and at this point
226  ** in its development we're not going to tamper with that.
227  ** @param result The buffer to use to return the string.
228  ** Returns NULL on failure.
229  ** @return The same buffer for convenience.
230  */
232 
233 /**
234  * Tells Tidy to use a different language for output.
235  * @param languageCode A Windows or POSIX language code, and must match
236  * a TIDY_LANGUAGE for an installed language.
237  * @result Indicates that a setting was applied, but not necessarily the
238  * specific request, i.e., true indicates a language and/or region
239  * was applied. If es_mx is requested but not installed, and es is
240  * installed, then es will be selected and this function will return
241  * true. However the opposite is not true; if es is requested but
242  * not present, Tidy will not try to select from the es_XX variants.
243  */
244 Bool tidySetLanguage( ctmbstr languageCode );
245 
246 /**
247  * Gets the current language used by Tidy.
248  */
250 
251 /**
252  * Provides a string given `messageType` in the current
253  * localization for `quantity`.
254  */
255 ctmbstr tidyLocalizedStringN( uint messageType, uint quantity );
256 
257 /**
258  * Provides a string given `messageType` in the current
259  * localization for the single case.
260  */
261 ctmbstr tidyLocalizedString( uint messageType );
262 
263 
264 /** @} */
265 /** @name Documentation Generation */
266 /** @{ */
267 
268 /**
269  * Provides a string given `messageType` in the default
270  * localization (which is `en`).
271  */
272 ctmbstr tidyDefaultString( uint messageType );
273 
274 /*
275  * Initializes the TidyIterator to point to the first item
276  * in Tidy's list of localization string keys. Note that
277  * these are provided for documentation generation purposes
278  * and probably aren't useful for LibTidy implementors.
279  */
280 TidyIterator getStringKeyList();
281 
282 /*
283  * Provides the next key value in Tidy's list of localized
284  * strings. Note that these are provided for documentation
285  * generation purposes and probably aren't useful to
286  * libtidy implementors.
287  */
288 uint getNextStringKey( TidyIterator* iter );
289 
290 /**
291  * Initializes the TidyIterator to point to the first item
292  * in Tidy's structure of Windows<->POSIX local mapping.
293  * Items can be retrieved with getNextWindowsLanguage();
294  */
295 TidyIterator getWindowsLanguageList();
296 
297 /**
298  * Returns the next record of type `localeMapItem` in
299  * Tidy's structure of Windows<->POSIX local mapping.
300  */
301 const tidyLocaleMapItem *getNextWindowsLanguage( TidyIterator* iter );
302 
303 /**
304  * Initializes the TidyIterator to point to the first item
305  * in Tidy's list of installed language codes.
306  * Items can be retrieved with getNextInstalledLanguage();
307  */
308 TidyIterator getInstalledLanguageList();
309 
310 /**
311  * Returns the next installed language.
312  */
313 ctmbstr getNextInstalledLanguage( TidyIterator* iter );
314 
315 
316 /**
317  * Initializes the TidyIterator to point to the first item
318  * in Tidy's list of error codes that can be return with
319  * `TidyReportFilter3`.
320  * Items can be retrieved with getNextErrorCode();
321  */
322 TidyIterator getErrorCodeList();
323 
324 /**
325  * Returns the next error code.
326  */
327 const tidyErrorFilterKeyItem *getNextErrorCode( TidyIterator* iter );
328 
329 
330 /** @} */
331 
332 #endif /* language_h */
Definition: language.h:189
Definition: language.h:186
ctmbstr tidyLocalizedStringN(uint messageType, uint quantity)
Provides a string given messageType in the current localization for quantity.
tidyMessageTypes
Defines all of the possible dictionary keys.
Definition: language.h:102
TidyIterator getWindowsLanguageList()
Initializes the TidyIterator to point to the first item in Tidy&#39;s structure of Windows<->POSIX local ...
Definition: language.h:143
Definition: language.h:169
Definition: language.h:123
ctmbstr key
Definition: language.h:80
Definition: language.h:144
Definition: language.h:146
uint getNextStringKey(TidyIterator *iter)
Definition: language.h:181
Definition: language.h:140
Definition: language.h:122
Definition: language.h:195
Definition: language.h:176
Definition: language.h:173
ctmbstr tidyGetLanguage()
Gets the current language used by Tidy.
Definition: language.h:162
Definition: language.h:178
Definition: language.h:136
Definition: language.h:126
Definition: language.h:190
Definition: language.h:127
ctmbstr getNextInstalledLanguage(TidyIterator *iter)
Returns the next installed language.
Definition: language.h:197
Definition: language.h:174
Definition: language.h:134
Definition: language.h:131
const tmbchar * ctmbstr
Definition: tidyplatform.h:556
Definition: language.h:156
languageDictionaryEntry const languageDictionary[600]
For now we&#39;ll just use an array to hold all of the dictionary entries.
Definition: language.h:43
tmbstr tidySystemLocale(tmbstr result)
Determines the current locale without affecting the C locale.
Definition: language.h:172
Definition: language.h:108
Definition: language.h:185
Definition: language.h:132
Definition: language.h:183
Definition: language.h:163
Describes a record for a localization string.
Definition: language.h:31
Definition: language.h:153
Definition: language.h:170
Definition: language.h:118
ctmbstr tidyDefaultString(uint messageType)
Provides a string given messageType in the default localization (which is en).
ctmbstr tidyErrorCodeAsString(uint code)
LibTidy users may want to use TidyReportFilter3 to enable their own localization lookup features...
Definition: language.h:158
Definition: language.h:175
Definition: language.h:202
Definition: language.h:160
Definition: language.h:119
Definition: language.h:192
Definition: language.h:125
Definition: language.h:112
Finally, a complete language definition.
Definition: language.h:52
Definition: language.h:120
Definition: language.h:137
const tidyErrorFilterKeyItem * getNextErrorCode(TidyIterator *iter)
Returns the next error code.
Bool
Definition: tidyplatform.h:593
Definition: language.h:117
The function getNextWindowsLanguage() returns pointers to this type; it gives LibTidy implementors th...
Definition: language.h:63
int value
Definition: language.h:81
Definition: language.h:171
Definition: language.h:168
Definition: language.h:135
Platform specifics
ctmbstr value
Definition: language.h:34
Definition: language.h:116
The function getNextErrorCode() returns pointers to this type; it gives LibTidy implementors the abil...
Definition: language.h:79
Definition: language.h:159
Definition: language.h:145
Definition: language.h:187
Definition: language.h:194
Bool tidySetLanguage(ctmbstr languageCode)
Tells Tidy to use a different language for output.
Definition: language.h:149
tmbchar * tmbstr
Definition: tidyplatform.h:555
Definition: language.h:193
Definition: language.h:188
uint pluralForm
Definition: language.h:33
Definition: language.h:121
TidyIterator getStringKeyList()
ctmbstr POSIXName
Definition: language.h:65
unsigned int uint
Definition: tidyplatform.h:525
Definition: language.h:141
Definition: language.h:198
Definition: language.h:191
Definition: language.h:124
Definition: language.h:152
uint(* whichPluralForm)(uint n)
Definition: language.h:53
Definition: language.h:105
Definition: language.h:199
Definition: language.h:167
Definition: language.h:115
Definition: language.h:151
ctmbstr winName
Definition: language.h:64
Definition: language.h:111
Definition: language.h:155
Definition: language.h:129
Definition: language.h:164
TidyIterator getErrorCodeList()
Initializes the TidyIterator to point to the first item in Tidy&#39;s list of error codes that can be ret...
Definition: language.h:148
Definition: language.h:142
const tidyLocaleMapItem * getNextWindowsLanguage(TidyIterator *iter)
Returns the next record of type localeMapItem in Tidy&#39;s structure of Windows<->POSIX local mapping...
Definition: language.h:196
Definition: language.h:139
ctmbstr tidyLocalizedString(uint messageType)
Provides a string given messageType in the current localization for the single case.
Definition: language.h:165
Definition: language.h:138
Definition: language.h:150
Definition: language.h:154
uint key
Definition: language.h:32
languageDictionary messages
Definition: language.h:54
Definition: language.h:184
Definition: language.h:128
Definition: language.h:182
Definition: language.h:147
Definition: language.h:133
Definition: language.h:161
Definition: language.h:179
Definition: language.h:130
Definition: language.h:166
TidyIterator getInstalledLanguageList()
Initializes the TidyIterator to point to the first item in Tidy&#39;s list of installed language codes...
Definition: language.h:177
Definition: language.h:180
Definition: language.h:157