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