1/* Public API for GNU gettext PO files - contained in libgettextpo. 2 Copyright (C) 2003-2007 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 24extern "C" { 25#endif 26 27 28/* =========================== Meta Information ============================ */ 29 30/* Version number: (major<<16) + (minor<<8) + subminor */ 31#define LIBGETTEXTPO_VERSION 0x001100 32extern int libgettextpo_version; 33 34/* ================================= Types ================================= */ 35 36/* A po_file_t represents the contents of a PO file. */ 37typedef struct po_file *po_file_t; 38 39/* A po_message_iterator_t represents an iterator through a domain of a 40 PO file. */ 41typedef struct po_message_iterator *po_message_iterator_t; 42 43/* A po_message_t represents a message in a PO file. */ 44typedef struct po_message *po_message_t; 45 46/* A po_filepos_t represents a string's position within a source file. */ 47typedef struct po_filepos *po_filepos_t; 48 49/* A po_error_handler handles error situations. */ 50struct 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}; 86typedef 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 */ 92struct 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}; 119typedef 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. */ 131extern 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 136extern 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 142extern 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. */ 146extern void po_file_free (po_file_t file); 147 148/* Return the names of the domains covered by a PO file in memory. */ 149extern 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. */ 157extern 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. */ 162extern 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. */ 167extern 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. */ 174extern po_message_iterator_t po_message_iterator (po_file_t file, const char *domain); 175 176/* Free an iterator. */ 177extern 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. */ 181extern 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. */ 186extern 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. */ 193extern 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. */ 197extern 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. */ 201extern void po_message_set_msgctxt (po_message_t message, const char *msgctxt); 202 203/* Return the msgid (untranslated English string) of a message. */ 204extern const char * po_message_msgid (po_message_t message); 205 206/* Change the msgid (untranslated English string) of a message. */ 207extern 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. */ 211extern 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. */ 215extern 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. */ 219extern 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. */ 223extern 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. */ 227extern 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. */ 231extern void po_message_set_msgstr_plural (po_message_t message, int index, const char *msgstr); 232 233/* Return the comments for a message. */ 234extern 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. */ 238extern void po_message_set_comments (po_message_t message, const char *comments); 239 240/* Return the extracted comments for a message. */ 241extern 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. */ 245extern 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. */ 249extern 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. */ 254extern 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. */ 261extern 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. */ 264extern const char * po_message_prev_msgctxt (po_message_t message); 265 266/* Change the previous context of a message. NULL is allowed. */ 267extern 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. */ 271extern 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. */ 275extern 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. */ 279extern 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. */ 283extern 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. */ 286extern int po_message_is_obsolete (po_message_t message); 287 288/* Change the obsolete mark of a message. */ 289extern void po_message_set_obsolete (po_message_t message, int obsolete); 290 291/* Return true if the message is marked fuzzy. */ 292extern int po_message_is_fuzzy (po_message_t message); 293 294/* Change the fuzzy mark of a message. */ 295extern 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"). */ 299extern 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. */ 302extern void po_message_set_format (po_message_t message, const char *format_type, /*bool*/int value); 303 304 305/* =========================== po_filepos_t API ============================ */ 306 307/* Return the file name. */ 308extern const char * po_filepos_file (po_filepos_t filepos); 309 310/* Return the line number where the string starts, or (size_t)(-1) if no line 311 number is available. */ 312extern size_t po_filepos_start_line (po_filepos_t filepos); 313 314 315/* ============================ Format type API ============================= */ 316 317/* Return a NULL terminated array of the supported format types. */ 318extern const char * const * po_format_list (void); 319 320/* Return the pretty name associated with a format type. 321 For example, for "csharp-format", return "C#". 322 Return NULL if the argument is not a supported format type. */ 323extern const char * po_format_pretty_name (const char *format_type); 324 325 326/* ============================= Checking API ============================== */ 327 328/* Test whether an entire file PO file is valid, like msgfmt does it. 329 If it is invalid, pass the reasons to the handler. */ 330extern void po_file_check_all (po_file_t file, po_xerror_handler_t handler); 331 332/* Test a single message, to be inserted in a PO file in memory, like msgfmt 333 does it. If it is invalid, pass the reasons to the handler. The iterator 334 is not modified by this call; it only specifies the file and the domain. */ 335extern void po_message_check_all (po_message_t message, po_message_iterator_t iterator, po_xerror_handler_t handler); 336 337/* Test whether the message translation is a valid format string if the message 338 is marked as being a format string. If it is invalid, pass the reasons to 339 the handler. */ 340#define po_message_check_format po_message_check_format_v2 341extern void po_message_check_format (po_message_t message, po_xerror_handler_t handler); 342 343 344#ifdef __cplusplus 345} 346#endif 347 348#endif /* _GETTEXT_PO_H */ 349