HTML Tidy  5.8.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 /*********************************************************************
5  * Localization support for HTML Tidy.
6  *
7  * This header provides the public (within libtidy) interface to
8  * basic localization support. To add your own localization, create
9  * a new `language_xx.h` file and add it to the struct in
10  * `language.c`.
11  *
12  * (c) 2015 HTACG
13  * See `tidy.h` for the copyright notice.
14  *********************************************************************/
15 
16 #include "forward.h"
17 
18 
19 /** @name Exposed Data Structures */
20 /** @{ */
21 
22 
23 /**
24  * These enumerations are used within instances of `languageDefinition`
25  * structures to provide additional metadata, and are localizable
26  * therein.
27  */
28 typedef enum {
29 
30  /* Specifies the language code for a particular language. */
32 
33  /* Marker for the last key in the structure. */
35 
37 
38 
39 /**
40  * Describes a record for a localization string.
41  * - key must correspond with one of Tidy's enums (see `tidyMessageTypes`
42  * below)
43  * - pluralForm corresponds to gettext plural forms case (not singularity).
44  * Most entries should be case 0, representing the single case.:
45  * https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html
46  */
47 typedef struct languageDictionaryEntry {
52 
53 
54 /**
55  * For now we'll just use an array to hold all of the dictionary
56  * entries. In the future we can convert this to a hash structure
57  * which will make looking up strings faster.
58  */
60 
61 
62 /**
63  * Finally, a complete language definition. The item `pluralForm`
64  * is a function pointer that will provide the correct plural
65  * form given the value `n`. The actual function is present in
66  * each language header and is language dependent.
67  */
68 typedef struct languageDefinition {
72 
73 
74 /**
75  * The function getNextWindowsLanguage() returns pointers to this type;
76  * it gives LibTidy implementors the ability to determine how Windows
77  * locale names are mapped to POSIX language codes.
78  */
79 typedef struct tidyLocaleMapItemImpl {
83 
84 
85 /** @} */
86 /** @name Localization Related Functions */
87 /** @{ */
88 
89 
90 /**
91  ** Determines the current locale without affecting the C locale.
92  ** Tidy has always used the default C locale, and at this point
93  ** in its development we're not going to tamper with that.
94  ** @param result The buffer to use to return the string.
95  ** Returns NULL on failure.
96  ** @return The same buffer for convenience.
97  */
98 TY_PRIVATE tmbstr TY_(tidySystemLocale)(tmbstr result);
99 
100 /**
101  * Tells Tidy to use a different language for output.
102  * @param languageCode A Windows or POSIX language code, and must match
103  * a TIDY_LANGUAGE for an installed language.
104  * @result Indicates that a setting was applied, but not necessarily the
105  * specific request, i.e., true indicates a language and/or region
106  * was applied. If es_mx is requested but not installed, and es is
107  * installed, then es will be selected and this function will return
108  * true. However the opposite is not true; if es is requested but
109  * not present, Tidy will not try to select from the es_XX variants.
110  */
112 
113 /**
114  * Gets the current language used by Tidy.
115  */
117 
118 
119 /**
120  * Indicates whether or not the current language was set by a
121  * LibTidy user or internally by the library. This flag prevents
122  * subsequently created instances of TidyDocument from changing the
123  * user's language.
124  * @returns Returns yes to indicate that the current language was
125  * specified by an API user.
126  */
127 TY_PRIVATE Bool TY_(tidyGetLanguageSetByUser)(void);
128 
129 
130 /**
131  * Specifies to LibTidy that the user (rather than the library)
132  * selected the current language. This flag prevents subsequently
133  * created instances of TidyDocument from changing the user's language.
134  */
135 TY_PRIVATE void TY_(tidySetLanguageSetByUser)( void );
136 
137 
138 /**
139  * Provides a string given `messageType` in the current
140  * localization for `quantity`.
141  */
143 
144 /**
145  * Provides a string given `messageType` in the current
146  * localization for the single case.
147  */
149 
150 
151 /** @} */
152 /** @name Documentation Generation */
153 /** @{ */
154 
155 
156 /**
157  * Provides a string given `messageType` in the default
158  * localization (which is `en`).
159  */
161 
162 /*
163  * Initializes the TidyIterator to point to the first item
164  * in Tidy's list of localization string keys. Note that
165  * these are provided for documentation generation purposes
166  * and probably aren't useful for LibTidy implementors.
167  */
168 TY_PRIVATE TidyIterator TY_(getStringKeyList)(void);
169 
170 /*
171  * Provides the next key value in Tidy's list of localized
172  * strings. Note that these are provided for documentation
173  * generation purposes and probably aren't useful to
174  * libtidy implementors.
175  */
176 TY_PRIVATE uint TY_(getNextStringKey)( TidyIterator* iter );
177 
178 /**
179  * Initializes the TidyIterator to point to the first item
180  * in Tidy's structure of Windows<->POSIX local mapping.
181  * Items can be retrieved with getNextWindowsLanguage();
182  */
184 
185 /**
186  * Returns the next record of type `localeMapItem` in
187  * Tidy's structure of Windows<->POSIX local mapping.
188  */
190 
191 /**
192  * Given a `tidyLocaleMapItemImpl, return the Windows name.
193  */
195 
196 /**
197  * Given a `tidyLocaleMapItemImpl, return the POSIX name.
198  */
200 
201 /**
202  * Initializes the TidyIterator to point to the first item
203  * in Tidy's list of installed language codes.
204  * Items can be retrieved with getNextInstalledLanguage();
205  */
207 
208 /**
209  * Returns the next installed language.
210  */
212 
213 
214 /** @} */
215 
216 #endif /* language_h */
#define TY_PRIVATE
Definition: forward.h:29
#define TY_(str)
Definition: forward.h:23
ctmbstr TIDY_CALL getNextInstalledLanguage(TidyIterator *iter)
Given a valid TidyIterator initiated with getInstalledLanguageList(), returns a string representing a...
TidyIterator TIDY_CALL getStringKeyList(void)
Initiates an iterator for a list of string key codes available in Tidy.
ctmbstr TIDY_CALL tidyLocalizedString(uint messageType)
Provides a string given messageType in the current localization for the single case.
ctmbstr TIDY_CALL TidyLangWindowsName(const tidyLocaleMapItem *item)
Given a tidyLocaleMapItem, return the Windows name.
ctmbstr TIDY_CALL tidyDefaultString(uint messageType)
Provides a string given messageType in the default localization (which is en).
TidyIterator TIDY_CALL getInstalledLanguageList(void)
Initiates an iterator for a list of Tidy's installed languages.
uint TIDY_CALL getNextStringKey(TidyIterator *iter)
Given a valid TidyIterator initiated with getStringKeyList(), returns an unsigned integer representin...
ctmbstr TIDY_CALL TidyLangPosixName(const tidyLocaleMapItem *item)
Given a tidyLocaleMapItem, return the POSIX name.
ctmbstr TIDY_CALL tidyLocalizedStringN(uint messageType, uint quantity)
Provides a string given messageType in the current localization for quantity.
Bool TIDY_CALL tidySetLanguage(ctmbstr languageCode)
Tells Tidy to use a different language for output.
TidyIterator TIDY_CALL getWindowsLanguageList(void)
Initiates an iterator for a list of Tidy's Windows<->POSIX locale mappings.
const tidyLocaleMapItem *TIDY_CALL getNextWindowsLanguage(TidyIterator *iter)
Given a valid TidyIterator initiated with getWindowsLanguageList(), returns a pointer to a tidyLocale...
ctmbstr TIDY_CALL tidyGetLanguage(void)
Gets the current language used by Tidy.
uint pluralForm
Definition: language.h:49
uint key
Definition: language.h:48
tidyLanguage
These enumerations are used within instances of languageDefinition structures to provide additional m...
Definition: language.h:28
@ TIDY_LANGUAGE
Definition: language.h:31
@ TIDY_MESSAGE_TYPE_LAST
Definition: language.h:34
ctmbstr value
Definition: language.h:50
ctmbstr POSIXName
Definition: language.h:81
ctmbstr winName
Definition: language.h:80
languageDictionaryEntry const languageDictionary[600]
For now we'll just use an array to hold all of the dictionary entries.
Definition: language.h:59
Describes a record for a localization string.
Definition: language.h:47
The function getNextWindowsLanguage() returns pointers to this type; it gives LibTidy implementors th...
Definition: language.h:79
Finally, a complete language definition.
Definition: language.h:68
uint(* whichPluralForm)(uint n)
Definition: language.h:69
languageDictionary messages
Definition: language.h:70
Bool
Definition: tidyplatform.h:647
unsigned int uint
Definition: tidyplatform.h:569
const tmbchar * ctmbstr
Definition: tidyplatform.h:609
tmbchar * tmbstr
Definition: tidyplatform.h:608