gettext: libgettextpo

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