gettext-tools/libgettextpo/gettext-po.in.h

   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 0x001203
  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 * 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 */