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