gnu/dist/gettext/gettext-tools/src/gettext-po.h

   1 /* Public API for GNU gettext PO files - contained in libgettextpo.
   2    Copyright (C) 2003-2005 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
  18
  19 #ifndef _GETTEXT_PO_H
  20 #define _GETTEXT_PO_H 1
  21
  22 #include <stdlib.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28
  29 /* =========================== Meta Information ============================ */
  30
  31 /* Version number: (major<<16) + (minor<<8) + subminor */
  32 #define LIBGETTEXTPO_VERSION 0x000E04
  33 extern int libgettextpo_version;
  34
  35 /* ================================= Types ================================= */
  36
  37 /* A po_file_t represents the contents of a PO file.  */
  38 typedef struct po_file *po_file_t;
  39
  40 /* A po_message_iterator_t represents an iterator through a domain of a
  41    PO file.  */
  42 typedef struct po_message_iterator *po_message_iterator_t;
  43
  44 /* A po_message_t represents a message in a PO file.  */
  45 typedef struct po_message *po_message_t;
  46
  47 /* A po_filepos_t represents a string's position within a source file.  */
  48 typedef struct po_filepos *po_filepos_t;
  49
  50 /* A po_error_handler handles error situations.  */
  51 struct 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
  60   /* Signal an error.  The error message is built from FORMAT and the following
  61      arguments.  The error location is at FILENAME line LINENO. ERRNUM, if
  62      nonzero, is an errno value.
  63      Must increment the error_message_count variable declared in error.h.
  64      Must not return if STATUS is nonzero.  */
  65   void (*error_at_line) (int status, int errnum,
  66                          const char *filename, unsigned int lineno,
  67                          const char *format, ...);
  68
  69   /* Signal a multiline warning.  The PREFIX applies to all lines of the
  70      MESSAGE.  Free the PREFIX and MESSAGE when done.  */
  71   void (*multiline_warning) (char *prefix, char *message);
  72
  73   /* Signal a multiline error.  The PREFIX applies to all lines of the
  74      MESSAGE.  Free the PREFIX and MESSAGE when done.
  75      Must increment the error_message_count variable declared in error.h if
  76      PREFIX is non-NULL.  */
  77   void (*multiline_error) (char *prefix, char *message);
  78 };
  79 typedef const struct po_error_handler *po_error_handler_t;
  80
  81 /* Memory allocation:
  82    The memory allocations performed by these functions use xmalloc(),
  83    therefore will cause a program exit if memory is exhausted.
  84    The memory allocated by po_file_read, and implicitly returned through
  85    the po_message_* functions, lasts until freed with po_file_free.  */
  86
  87
  88 /* ============================= po_file_t API ============================= */
  89
  90 /* Create an empty PO file representation in memory.  */
  91 extern po_file_t po_file_create (void);
  92
  93 /* Read a PO file into memory.
  94    Return its contents.  Upon failure, return NULL and set errno.  */
  95 #define po_file_read po_file_read_v2
  96 extern po_file_t po_file_read (const char *filename,
  97                                po_error_handler_t handler);
  98
  99 /* Write an in-memory PO file to a file.
 100    Upon failure, return NULL and set errno.  */
 101 extern po_file_t po_file_write (po_file_t file, const char *filename,
 102                                 po_error_handler_t handler);
 103
 104 /* Free a PO file from memory.  */
 105 extern void po_file_free (po_file_t file);
 106
 107 /* Return the names of the domains covered by a PO file in memory.  */
 108 extern const char * const * po_file_domains (po_file_t file);
 109
 110
 111 /* =========================== Header entry API ============================ */
 112
 113 /* Return the header entry of a domain of a PO file in memory.
 114    The domain NULL denotes the default domain.
 115    Return NULL if there is no header entry.  */
 116 extern const char * po_file_domain_header (po_file_t file, const char *domain);
 117
 118 /* Return the value of a field in a header entry.
 119    The return value is either a freshly allocated string, to be freed by the
 120    caller, or NULL.  */
 121 extern char * po_header_field (const char *header, const char *field);
 122
 123 /* Return the header entry with a given field set to a given value.  The field
 124    is added if necessary.
 125    The return value is a freshly allocated string.  */
 126 extern char * po_header_set_field (const char *header, const char *field, const char *value);
 127
 128
 129 /* ======================= po_message_iterator_t API ======================= */
 130
 131 /* Create an iterator for traversing a domain of a PO file in memory.
 132    The domain NULL denotes the default domain.  */
 133 extern po_message_iterator_t po_message_iterator (po_file_t file, const char *domain);
 134
 135 /* Free an iterator.  */
 136 extern void po_message_iterator_free (po_message_iterator_t iterator);
 137
 138 /* Return the next message, and advance the iterator.
 139    Return NULL at the end of the message list.  */
 140 extern po_message_t po_next_message (po_message_iterator_t iterator);
 141
 142 /* Insert a message in a PO file in memory, in the domain and at the position
 143    indicated by the iterator.  The iterator thereby advances past the freshly
 144    inserted message.  */
 145 extern void po_message_insert (po_message_iterator_t iterator, po_message_t message);
 146
 147
 148 /* =========================== po_message_t API ============================ */
 149
 150 /* Return a freshly constructed message.
 151    To finish initializing the message, you must set the msgid and msgstr.  */
 152 extern po_message_t po_message_create (void);
 153
 154 /* Return the msgid (untranslated English string) of a message.  */
 155 extern const char * po_message_msgid (po_message_t message);
 156
 157 /* Change the msgid (untranslated English string) of a message.  */
 158 extern void po_message_set_msgid (po_message_t message, const char *msgid);
 159
 160 /* Return the msgid_plural (untranslated English plural string) of a message,
 161    or NULL for a message without plural.  */
 162 extern const char * po_message_msgid_plural (po_message_t message);
 163
 164 /* Change the msgid_plural (untranslated English plural string) of a message.
 165    NULL means a message without plural.  */
 166 extern void po_message_set_msgid_plural (po_message_t message, const char *msgid_plural);
 167
 168 /* Return the msgstr (translation) of a message.
 169    Return the empty string for an untranslated message.  */
 170 extern const char * po_message_msgstr (po_message_t message);
 171
 172 /* Change the msgstr (translation) of a message.
 173    Use an empty string to denote an untranslated message.  */
 174 extern void po_message_set_msgstr (po_message_t message, const char *msgstr);
 175
 176 /* Return the msgstr[index] for a message with plural handling, or
 177    NULL when the index is out of range or for a message without plural.  */
 178 extern const char * po_message_msgstr_plural (po_message_t message, int index);
 179
 180 /* Change the msgstr[index] for a message with plural handling.
 181    Use a NULL value at the end to reduce the number of plural forms.  */
 182 extern void po_message_set_msgstr_plural (po_message_t message, int index, const char *msgstr);
 183
 184 /* Return the comments for a message.  */
 185 extern const char * po_message_comments (po_message_t message);
 186
 187 /* Change the comments for a message.
 188    comments should be a multiline string, ending in a newline, or empty.  */
 189 extern void po_message_set_comments (po_message_t message, const char *comments);
 190
 191 /* Return the extracted comments for a message.  */
 192 extern const char * po_message_extracted_comments (po_message_t message);
 193
 194 /* Change the extracted comments for a message.
 195    comments should be a multiline string, ending in a newline, or empty.  */
 196 extern void po_message_set_extracted_comments (po_message_t message, const char *comments);
 197
 198 /* Return the i-th file position for a message, or NULL if i is out of
 199    range.  */
 200 extern po_filepos_t po_message_filepos (po_message_t message, int i);
 201
 202 /* Remove the i-th file position from a message.
 203    The indices of all following file positions for the message are decremented
 204    by one.  */
 205 extern void po_message_remove_filepos (po_message_t message, int i);
 206
 207 /* Add a file position to a message, if it is not already present for the
 208    message.
 209    file is the file name.
 210    start_line is the line number where the string starts, or (size_t)(-1) if no
 211    line number is available.  */
 212 extern void po_message_add_filepos (po_message_t message, const char *file, size_t start_line);
 213
 214 /* Return true if the message is marked obsolete.  */
 215 extern int po_message_is_obsolete (po_message_t message);
 216
 217 /* Change the obsolete mark of a message.  */
 218 extern void po_message_set_obsolete (po_message_t message, int obsolete);
 219
 220 /* Return true if the message is marked fuzzy.  */
 221 extern int po_message_is_fuzzy (po_message_t message);
 222
 223 /* Change the fuzzy mark of a message.  */
 224 extern void po_message_set_fuzzy (po_message_t message, int fuzzy);
 225
 226 /* Return true if the message is marked as being a format string of the given
 227    type (e.g. "c-format").  */
 228 extern int po_message_is_format (po_message_t message, const char *format_type);
 229
 230 /* Change the format string mark for a given type of a message.  */
 231 extern void po_message_set_format (po_message_t message, const char *format_type, /*bool*/int value);
 232
 233 /* Test whether the message translation is a valid format string if the message
 234    is marked as being a format string.  If it is invalid, pass the reasons to
 235    the handler.  */
 236 extern void po_message_check_format (po_message_t message, po_error_handler_t handler);
 237
 238
 239 /* =========================== po_filepos_t API ============================ */
 240
 241 /* Return the file name.  */
 242 extern const char * po_filepos_file (po_filepos_t filepos);
 243
 244 /* Return the line number where the string starts, or (size_t)(-1) if no line
 245    number is available.  */
 246 extern size_t po_filepos_start_line (po_filepos_t filepos);
 247
 248
 249 #ifdef __cplusplus
 250 }
 251 #endif
 252
 253 #endif /* _GETTEXT_PO_H */