---

---

---

001: /* Public API for GNU gettext PO files - contained in libgettextpo.
002:    Copyright (C) 2003-2008, 2010 Free Software Foundation, Inc.
003:    Written by Bruno Haible <bruno@clisp.org>, 2003.
004: 
005:    This program is free software: you can redistribute it and/or modify
006:    it under the terms of the GNU General Public License as published by
007:    the Free Software Foundation; either version 3 of the License, or
008:    (at your option) any later version.
009: 
010:    This program is distributed in the hope that it will be useful,
011:    but WITHOUT ANY WARRANTY; without even the implied warranty of
012:    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013:    GNU General Public License for more details.
014: 
015:    You should have received a copy of the GNU General Public License
016:    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
017: 
018: #ifndef _GETTEXT_PO_H
019: #define _GETTEXT_PO_H 1
020: 
021: #include <stdlib.h>
022: 
023: #ifdef __cplusplus
024: extern "C" {
025: #endif
026: 
027: 
028: /* =========================== Meta Information ============================ */
029: 
030: /* Version number: (major<<16) + (minor<<8) + subminor */
031: #define LIBGETTEXTPO_VERSION 0x001201
032: extern int libgettextpo_version;
033: 
034: /* ================================= Types ================================= */
035: 
036: /* A po_file_t represents the contents of a PO file.  */
037: typedef struct po_file *po_file_t;
038: 
039: /* A po_message_iterator_t represents an iterator through a domain of a
040:    PO file.  */
041: typedef struct po_message_iterator *po_message_iterator_t;
042: 
043: /* A po_message_t represents a message in a PO file.  */
044: typedef struct po_message *po_message_t;
045: 
046: /* A po_filepos_t represents a string's position within a source file.  */
047: typedef struct po_filepos *po_filepos_t;
048: 
049: /* A po_error_handler handles error situations.  */
050: struct po_error_handler
051: {
052:   /* Signal an error.  The error message is built from FORMAT and the following
053:      arguments.  ERRNUM, if nonzero, is an errno value.
054:      Must increment the error_message_count variable declared in error.h.
055:      Must not return if STATUS is nonzero.  */
056:   void (*error) (int status, int errnum,
057:                  const char *format, ...)
058: #if ((__GNUC__ == 3 && __GNUC_MINOR__ >= 1) || __GNUC__ > 3) && !__STRICT_ANSI__
059:   __attribute__ ((__format__ (__printf__, 3, 4)))
060: #endif
061:   ;
062: 
063:   /* Signal an error.  The error message is built from FORMAT and the following
064:      arguments.  The error location is at FILENAME line LINENO. ERRNUM, if
065:      nonzero, is an errno value.
066:      Must increment the error_message_count variable declared in error.h.
067:      Must not return if STATUS is nonzero.  */
068:   void (*error_at_line) (int status, int errnum,
069:                          const char *filename, unsigned int lineno,
070:                          const char *format, ...)
071: #if ((__GNUC__ == 3 && __GNUC_MINOR__ >= 1) || __GNUC__ > 3) && !__STRICT_ANSI__
072:   __attribute__ ((__format__ (__printf__, 5, 6)))
073: #endif
074:   ;
075: 
076:   /* Signal a multiline warning.  The PREFIX applies to all lines of the
077:      MESSAGE.  Free the PREFIX and MESSAGE when done.  */
078:   void (*multiline_warning) (char *prefix, char *message);
079: 
080:   /* Signal a multiline error.  The PREFIX applies to all lines of the
081:      MESSAGE.  Free the PREFIX and MESSAGE when done.
082:      Must increment the error_message_count variable declared in error.h if
083:      PREFIX is non-NULL.  */
084:   void (*multiline_error) (char *prefix, char *message);
085: };
086: typedef const struct po_error_handler *po_error_handler_t;
087: 
088: /* A po_xerror_handler handles warnings, error and fatal error situations.  */
089: #define PO_SEVERITY_WARNING     0 /* just a warning, tell the user */
090: #define PO_SEVERITY_ERROR       1 /* an error, the operation cannot complete */
091: #define PO_SEVERITY_FATAL_ERROR 2 /* an error, the operation must be aborted */
092: struct po_xerror_handler
093: {
094:   /* Signal a problem of the given severity.
095:      MESSAGE and/or FILENAME + LINENO indicate where the problem occurred.
096:      If FILENAME is NULL, FILENAME and LINENO and COLUMN should be ignored.
097:      If LINENO is (size_t)(-1), LINENO and COLUMN should be ignored.
098:      If COLUMN is (size_t)(-1), it should be ignored.
099:      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 * po_header_field (const char *header, 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 * po_header_set_field (const char *header, 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_comments (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_set_comments (po_message_t message, const char *comments);
239: 
240: /* Return the extracted comments for a message.  */
241: extern const char * po_message_extracted_comments (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_set_extracted_comments (po_message_t message, const char *comments);
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: 

---

---

---