[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
9.12 Writing your own programs that process PO files
For the tasks for which a combination of ‘msgattrib’, ‘msgcat’ etc. is not sufficient, a set of C functions is provided in a library, to make it possible to process PO files in your own programs. When you use this library, you don’t need to write routines to parse the PO file; instead, you retrieve a pointer in memory to each of messages contained in the PO file. Functions for writing PO files are not provided at this time.
The functions are declared in the header file ‘<gettext-po.h>’, and are defined in a library called ‘libgettextpo’.
- Data Type: po_file_t
This is a pointer type that refers to the contents of a PO file, after it has been read into memory.
- Data Type: po_message_iterator_t
This is a pointer type that refers to an iterator that produces a sequence of messages.
- Data Type: po_message_t
This is a pointer type that refers to a message of a PO file, including its translation.
- Function: po_file_t po_file_read (const char *filename)
The
po_file_read
function reads a PO file into memory. The file name is given as argument. The return value is a handle to the PO file’s contents, valid untilpo_file_free
is called on it. In case of error, the return value isNULL
, anderrno
is set.
- Function: void po_file_free (po_file_t file)
The
po_file_free
function frees a PO file’s contents from memory, including all messages that are only implicitly accessible through iterators.
- Function: const char * const * po_file_domains (po_file_t file)
The
po_file_domains
function returns the domains for which the given PO file has messages. The return value is aNULL
terminated array which is valid as long as the file handle is valid. For PO files which contain no ‘domain’ directive, the return value contains only one domain, namely the default domain"messages"
.
- Function: po_message_iterator_t po_message_iterator (po_file_t file, const char *domain)
The
po_message_iterator
returns an iterator that will produce the messages of file that belong to the given domain. If domain isNULL
, the default domain is used instead. To list the messages, use the functionpo_next_message
repeatedly.
- Function: void po_message_iterator_free (po_message_iterator_t iterator)
The
po_message_iterator_free
function frees an iterator previously allocated through thepo_message_iterator
function.
- Function: po_message_t po_next_message (po_message_iterator_t iterator)
The
po_next_message
function returns the next message from iterator and advances the iterator. It returnsNULL
when the iterator has reached the end of its message list.
The following functions returns details of a po_message_t
. Recall
that the results are valid as long as the file handle is valid.
- Function: const char * po_message_msgid (po_message_t message)
The
po_message_msgid
function returns themsgid
(untranslated English string) of a message. This is guaranteed to be non-NULL
.
- Function: const char * po_message_msgid_plural (po_message_t message)
The
po_message_msgid_plural
function returns themsgid_plural
(untranslated English plural string) of a message with plurals, orNULL
for a message without plural.
- Function: const char * po_message_msgstr (po_message_t message)
The
po_message_msgstr
function returns themsgstr
(translation) of a message. For an untranslated message, the return value is an empty string.
- Function: const char * po_message_msgstr_plural (po_message_t message, int index)
The
po_message_msgstr_plural
function returns themsgstr[index]
of a message with plurals, orNULL
when the index is out of range or for a message without plural.
Here is an example code how these functions can be used.
const char *filename = …; po_file_t file = po_file_read (filename); if (file == NULL) error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename); { const char * const *domains = po_file_domains (file); const char * const *domainp; for (domainp = domains; *domainp; domainp++) { const char *domain = *domainp; po_message_iterator_t iterator = po_message_iterator (file, domain); for (;;) { po_message_t *message = po_next_message (iterator); if (message == NULL) break; { const char *msgid = po_message_msgid (message); const char *msgstr = po_message_msgstr (message); … } } po_message_iterator_free (iterator); } } po_file_free (file);
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on June 7, 2014 using texi2html 5.0.