1 | /* Public API for GNU gettext PO files - contained in libgettextpo. |
2 | Copyright (C) 2003-2008, 2010 Free Software Foundation, Inc. |
3 | Written by Bruno Haible <bruno@clisp.org>, 2003. |
4 | |
5 | This program is free software: you can redistribute it and/or modify |
6 | it under the terms of the GNU General Public License as published by |
7 | the Free Software Foundation; either version 3 of the License, or |
8 | (at your option) any later version. |
9 | |
10 | This program is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
13 | GNU General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU General Public License |
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
17 | |
18 | #ifndef _GETTEXT_PO_H |
19 | #define _GETTEXT_PO_H 1 |
20 | |
21 | #include <stdlib.h> |
22 | |
23 | #ifdef __cplusplus |
24 | extern "C" { |
25 | #endif |
26 | |
27 | |
28 | /* =========================== Meta Information ============================ */ |
29 | |
30 | /* Version number: (major<<16) + (minor<<8) + subminor */ |
31 | #define LIBGETTEXTPO_VERSION 0x001302 |
32 | extern int libgettextpo_version; |
33 | |
34 | /* ================================= Types ================================= */ |
35 | |
36 | /* A po_file_t represents the contents of a PO file. */ |
37 | typedef struct po_file *po_file_t; |
38 | |
39 | /* A po_message_iterator_t represents an iterator through a domain of a |
40 | PO file. */ |
41 | typedef struct po_message_iterator *po_message_iterator_t; |
42 | |
43 | /* A po_message_t represents a message in a PO file. */ |
44 | typedef struct po_message *po_message_t; |
45 | |
46 | /* A po_filepos_t represents a string's position within a source file. */ |
47 | typedef struct po_filepos *po_filepos_t; |
48 | |
49 | /* A po_error_handler handles error situations. */ |
50 | struct po_error_handler |
51 | { |
52 | /* Signal an error. The error message is built from FORMAT and the following |
53 | arguments. ERRNUM, if nonzero, is an errno value. |
54 | Must increment the error_message_count variable declared in error.h. |
55 | Must not return if STATUS is nonzero. */ |
56 | void (*error) (int status, int errnum, |
57 | const char *format, ...) |
58 | #if ((__GNUC__ == 3 && __GNUC_MINOR__ >= 1) || __GNUC__ > 3) && !__STRICT_ANSI__ |
59 | __attribute__ ((__format__ (__printf__, 3, 4))) |
60 | #endif |
61 | ; |
62 | |
63 | /* Signal an error. The error message is built from FORMAT and the following |
64 | arguments. The error location is at FILENAME line LINENO. ERRNUM, if |
65 | nonzero, is an errno value. |
66 | Must increment the error_message_count variable declared in error.h. |
67 | Must not return if STATUS is nonzero. */ |
68 | void (*error_at_line) (int status, int errnum, |
69 | const char *filename, unsigned int lineno, |
70 | const char *format, ...) |
71 | #if ((__GNUC__ == 3 && __GNUC_MINOR__ >= 1) || __GNUC__ > 3) && !__STRICT_ANSI__ |
72 | __attribute__ ((__format__ (__printf__, 5, 6))) |
73 | #endif |
74 | ; |
75 | |
76 | /* Signal a multiline warning. The PREFIX applies to all lines of the |
77 | MESSAGE. Free the PREFIX and MESSAGE when done. */ |
78 | void (*multiline_warning) (char *prefix, char *message); |
79 | |
80 | /* Signal a multiline error. The PREFIX applies to all lines of the |
81 | MESSAGE. Free the PREFIX and MESSAGE when done. |
82 | Must increment the error_message_count variable declared in error.h if |
83 | PREFIX is non-NULL. */ |
84 | void (*multiline_error) (char *prefix, char *message); |
85 | }; |
86 | typedef const struct po_error_handler *po_error_handler_t; |
87 | |
88 | /* A po_xerror_handler handles warnings, error and fatal error situations. */ |
89 | #define PO_SEVERITY_WARNING 0 /* just a warning, tell the user */ |
90 | #define PO_SEVERITY_ERROR 1 /* an error, the operation cannot complete */ |
91 | #define PO_SEVERITY_FATAL_ERROR 2 /* an error, the operation must be aborted */ |
92 | struct po_xerror_handler |
93 | { |
94 | /* Signal a problem of the given severity. |
95 | MESSAGE and/or FILENAME + LINENO indicate where the problem occurred. |
96 | If FILENAME is NULL, FILENAME and LINENO and COLUMN should be ignored. |
97 | If LINENO is (size_t)(-1), LINENO and COLUMN should be ignored. |
98 | If COLUMN is (size_t)(-1), it should be ignored. |
99 | MESSAGE_TEXT is the problem description (if MULTILINE_P is true, |
100 | multiple lines of text, each terminated with a newline, otherwise |
101 | usually a single line). |
102 | Must not return if SEVERITY is PO_SEVERITY_FATAL_ERROR. */ |
103 | void (*xerror) (int severity, |
104 | po_message_t message, |
105 | const char *filename, size_t lineno, size_t column, |
106 | int multiline_p, const char *message_text); |
107 | /* Signal a problem that refers to two messages. |
108 | Similar to two calls to xerror. |
109 | If possible, a "..." can be appended to MESSAGE_TEXT1 and prepended to |
110 | MESSAGE_TEXT2. */ |
111 | void (*xerror2) (int severity, |
112 | po_message_t message1, |
113 | const char *filename1, size_t lineno1, size_t column1, |
114 | int multiline_p1, const char *message_text1, |
115 | po_message_t message2, |
116 | const char *filename2, size_t lineno2, size_t column2, |
117 | int multiline_p2, const char *message_text2); |
118 | }; |
119 | typedef const struct po_xerror_handler *po_xerror_handler_t; |
120 | |
121 | /* Memory allocation: |
122 | The memory allocations performed by these functions use xmalloc(), |
123 | therefore will cause a program exit if memory is exhausted. |
124 | The memory allocated by po_file_read, and implicitly returned through |
125 | the po_message_* functions, lasts until freed with po_file_free. */ |
126 | |
127 | |
128 | /* ============================= po_file_t API ============================= */ |
129 | |
130 | /* Create an empty PO file representation in memory. */ |
131 | extern po_file_t po_file_create (void); |
132 | |
133 | /* Read a PO file into memory. |
134 | Return its contents. Upon failure, return NULL and set errno. */ |
135 | #define po_file_read po_file_read_v3 |
136 | extern po_file_t po_file_read (const char *filename, |
137 | po_xerror_handler_t handler); |
138 | |
139 | /* Write an in-memory PO file to a file. |
140 | Upon failure, return NULL and set errno. */ |
141 | #define po_file_write po_file_write_v2 |
142 | extern po_file_t po_file_write (po_file_t file, const char *filename, |
143 | po_xerror_handler_t handler); |
144 | |
145 | /* Free a PO file from memory. */ |
146 | extern void po_file_free (po_file_t file); |
147 | |
148 | /* Return the names of the domains covered by a PO file in memory. */ |
149 | extern const char * const * po_file_domains (po_file_t file); |
150 | |
151 | |
152 | /* =========================== Header entry API ============================ */ |
153 | |
154 | /* Return the header entry of a domain of a PO file in memory. |
155 | The domain NULL denotes the default domain. |
156 | Return NULL if there is no header entry. */ |
157 | extern const char * po_file_domain_header (po_file_t file, const char *domain); |
158 | |
159 | /* Return the value of a field in a header entry. |
160 | The return value is either a freshly allocated string, to be freed by the |
161 | caller, or NULL. */ |
162 | extern char * (const char *, const char *field); |
163 | |
164 | /* Return the header entry with a given field set to a given value. The field |
165 | is added if necessary. |
166 | The return value is a freshly allocated string. */ |
167 | extern char * (const char *, const char *field, const char *value); |
168 | |
169 | |
170 | /* ======================= po_message_iterator_t API ======================= */ |
171 | |
172 | /* Create an iterator for traversing a domain of a PO file in memory. |
173 | The domain NULL denotes the default domain. */ |
174 | extern po_message_iterator_t po_message_iterator (po_file_t file, const char *domain); |
175 | |
176 | /* Free an iterator. */ |
177 | extern void po_message_iterator_free (po_message_iterator_t iterator); |
178 | |
179 | /* Return the next message, and advance the iterator. |
180 | Return NULL at the end of the message list. */ |
181 | extern po_message_t po_next_message (po_message_iterator_t iterator); |
182 | |
183 | /* Insert a message in a PO file in memory, in the domain and at the position |
184 | indicated by the iterator. The iterator thereby advances past the freshly |
185 | inserted message. */ |
186 | extern void po_message_insert (po_message_iterator_t iterator, po_message_t message); |
187 | |
188 | |
189 | /* =========================== po_message_t API ============================ */ |
190 | |
191 | /* Return a freshly constructed message. |
192 | To finish initializing the message, you must set the msgid and msgstr. */ |
193 | extern po_message_t po_message_create (void); |
194 | |
195 | /* Return the context of a message, or NULL for a message not restricted to a |
196 | context. */ |
197 | extern const char * po_message_msgctxt (po_message_t message); |
198 | |
199 | /* Change the context of a message. NULL means a message not restricted to a |
200 | context. */ |
201 | extern void po_message_set_msgctxt (po_message_t message, const char *msgctxt); |
202 | |
203 | /* Return the msgid (untranslated English string) of a message. */ |
204 | extern const char * po_message_msgid (po_message_t message); |
205 | |
206 | /* Change the msgid (untranslated English string) of a message. */ |
207 | extern void po_message_set_msgid (po_message_t message, const char *msgid); |
208 | |
209 | /* Return the msgid_plural (untranslated English plural string) of a message, |
210 | or NULL for a message without plural. */ |
211 | extern const char * po_message_msgid_plural (po_message_t message); |
212 | |
213 | /* Change the msgid_plural (untranslated English plural string) of a message. |
214 | NULL means a message without plural. */ |
215 | extern void po_message_set_msgid_plural (po_message_t message, const char *msgid_plural); |
216 | |
217 | /* Return the msgstr (translation) of a message. |
218 | Return the empty string for an untranslated message. */ |
219 | extern const char * po_message_msgstr (po_message_t message); |
220 | |
221 | /* Change the msgstr (translation) of a message. |
222 | Use an empty string to denote an untranslated message. */ |
223 | extern void po_message_set_msgstr (po_message_t message, const char *msgstr); |
224 | |
225 | /* Return the msgstr[index] for a message with plural handling, or |
226 | NULL when the index is out of range or for a message without plural. */ |
227 | extern const char * po_message_msgstr_plural (po_message_t message, int index); |
228 | |
229 | /* Change the msgstr[index] for a message with plural handling. |
230 | Use a NULL value at the end to reduce the number of plural forms. */ |
231 | extern void po_message_set_msgstr_plural (po_message_t message, int index, const char *msgstr); |
232 | |
233 | /* Return the comments for a message. */ |
234 | extern const char * (po_message_t message); |
235 | |
236 | /* Change the comments for a message. |
237 | comments should be a multiline string, ending in a newline, or empty. */ |
238 | extern void (po_message_t message, const char *); |
239 | |
240 | /* Return the extracted comments for a message. */ |
241 | extern const char * (po_message_t message); |
242 | |
243 | /* Change the extracted comments for a message. |
244 | comments should be a multiline string, ending in a newline, or empty. */ |
245 | extern void (po_message_t message, const char *); |
246 | |
247 | /* Return the i-th file position for a message, or NULL if i is out of |
248 | range. */ |
249 | extern po_filepos_t po_message_filepos (po_message_t message, int i); |
250 | |
251 | /* Remove the i-th file position from a message. |
252 | The indices of all following file positions for the message are decremented |
253 | by one. */ |
254 | extern void po_message_remove_filepos (po_message_t message, int i); |
255 | |
256 | /* Add a file position to a message, if it is not already present for the |
257 | message. |
258 | file is the file name. |
259 | start_line is the line number where the string starts, or (size_t)(-1) if no |
260 | line number is available. */ |
261 | extern void po_message_add_filepos (po_message_t message, const char *file, size_t start_line); |
262 | |
263 | /* Return the previous context of a message, or NULL for none. */ |
264 | extern const char * po_message_prev_msgctxt (po_message_t message); |
265 | |
266 | /* Change the previous context of a message. NULL is allowed. */ |
267 | extern void po_message_set_prev_msgctxt (po_message_t message, const char *prev_msgctxt); |
268 | |
269 | /* Return the previous msgid (untranslated English string) of a message, or |
270 | NULL for none. */ |
271 | extern const char * po_message_prev_msgid (po_message_t message); |
272 | |
273 | /* Change the previous msgid (untranslated English string) of a message. |
274 | NULL is allowed. */ |
275 | extern void po_message_set_prev_msgid (po_message_t message, const char *prev_msgid); |
276 | |
277 | /* Return the previous msgid_plural (untranslated English plural string) of a |
278 | message, or NULL for none. */ |
279 | extern const char * po_message_prev_msgid_plural (po_message_t message); |
280 | |
281 | /* Change the previous msgid_plural (untranslated English plural string) of a |
282 | message. NULL is allowed. */ |
283 | extern void po_message_set_prev_msgid_plural (po_message_t message, const char *prev_msgid_plural); |
284 | |
285 | /* Return true if the message is marked obsolete. */ |
286 | extern int po_message_is_obsolete (po_message_t message); |
287 | |
288 | /* Change the obsolete mark of a message. */ |
289 | extern void po_message_set_obsolete (po_message_t message, int obsolete); |
290 | |
291 | /* Return true if the message is marked fuzzy. */ |
292 | extern int po_message_is_fuzzy (po_message_t message); |
293 | |
294 | /* Change the fuzzy mark of a message. */ |
295 | extern void po_message_set_fuzzy (po_message_t message, int fuzzy); |
296 | |
297 | /* Return true if the message is marked as being a format string of the given |
298 | type (e.g. "c-format"). */ |
299 | extern int po_message_is_format (po_message_t message, const char *format_type); |
300 | |
301 | /* Change the format string mark for a given type of a message. */ |
302 | extern void po_message_set_format (po_message_t message, const char *format_type, /*bool*/int value); |
303 | |
304 | /* If a numeric range of a message is set, return true and store the minimum |
305 | and maximum value in *MINP and *MAXP. */ |
306 | extern int po_message_is_range (po_message_t message, int *minp, int *maxp); |
307 | |
308 | /* Change the numeric range of a message. MIN and MAX must be non-negative, |
309 | with MIN < MAX. Use MIN = MAX = -1 to remove the numeric range of a |
310 | message. */ |
311 | extern void po_message_set_range (po_message_t message, int min, int max); |
312 | |
313 | |
314 | /* =========================== po_filepos_t API ============================ */ |
315 | |
316 | /* Return the file name. */ |
317 | extern const char * po_filepos_file (po_filepos_t filepos); |
318 | |
319 | /* Return the line number where the string starts, or (size_t)(-1) if no line |
320 | number is available. */ |
321 | extern size_t po_filepos_start_line (po_filepos_t filepos); |
322 | |
323 | |
324 | /* ============================ Format type API ============================= */ |
325 | |
326 | /* Return a NULL terminated array of the supported format types. */ |
327 | extern const char * const * po_format_list (void); |
328 | |
329 | /* Return the pretty name associated with a format type. |
330 | For example, for "csharp-format", return "C#". |
331 | Return NULL if the argument is not a supported format type. */ |
332 | extern const char * po_format_pretty_name (const char *format_type); |
333 | |
334 | |
335 | /* ============================= Checking API ============================== */ |
336 | |
337 | /* Test whether an entire file PO file is valid, like msgfmt does it. |
338 | If it is invalid, pass the reasons to the handler. */ |
339 | extern void po_file_check_all (po_file_t file, po_xerror_handler_t handler); |
340 | |
341 | /* Test a single message, to be inserted in a PO file in memory, like msgfmt |
342 | does it. If it is invalid, pass the reasons to the handler. The iterator |
343 | is not modified by this call; it only specifies the file and the domain. */ |
344 | extern void po_message_check_all (po_message_t message, po_message_iterator_t iterator, po_xerror_handler_t handler); |
345 | |
346 | /* Test whether the message translation is a valid format string if the message |
347 | is marked as being a format string. If it is invalid, pass the reasons to |
348 | the handler. */ |
349 | #define po_message_check_format po_message_check_format_v2 |
350 | extern void po_message_check_format (po_message_t message, po_xerror_handler_t handler); |
351 | |
352 | |
353 | #ifdef __cplusplus |
354 | } |
355 | #endif |
356 | |
357 | #endif /* _GETTEXT_PO_H */ |
358 | |