File: gettext.info,  Node: libgettextpo,  Prev: Other tools,  Up: Manipulating

10.13 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 those memory structures to a file
after working with them are provided too.

   The functions are declared in the header file ‘’, and
are defined in a library called ‘libgettextpo’.

   The library is multithread-safe in the following sense: Different
threads can safely use the various functions simultaneously on unrelated
data objects.  For example, if several threads have created separate
‘po_file_t’ objects, each of them can safely work on its respective
‘po_file_t’ object, without caring about the other threads.

* Menu:

* Error Handling::              Error handling functions
* po_file_t API::               File management
* po_message_iterator_t API::   Message iteration
* po_message_t API::            The basic units of the file
* PO Header Entry API::         Meta information of the file
* po_filepos_t API::            References to the sources
* Format Type API::             Supported format types
* po_flag_iterator_t API::      Flag iteration
* Checking API::                Enforcing constraints

   The following example shows code how these functions can be used.
Error handling code is omitted, as its implementation is delegated to
the user provided functions.

     struct po_xerror_handler handler =
       {
         .xerror = ...,
         .xerror2 = ...
       };
     const char *filename = ...;
     /* Read the file into memory.  */
     po_file_t file = po_file_read (filename, &handler);

     {
       const char * const *domains = po_file_domains (file);
       const char * const *domainp;

       /* Iterate the domains contained in the file.  */
       for (domainp = domains; *domainp; domainp++)
         {
           po_message_t *message;
           const char *domain = *domainp;
           po_message_iterator_t iterator = po_message_iterator (file, domain);

           /* Iterate each message inside the domain.  */
           while ((message = po_next_message (iterator)) != NULL)
             {
               /* Read data from the message ...  */
               const char *msgid = po_message_msgid (message);
               const char *msgstr = po_message_msgstr (message);

               ...

               /* Modify its contents ...  */
               if (perform_some_tests (msgid, msgstr))
                 po_message_set_fuzzy (message, 1);

               ...
             }
           /* Always release returned po_message_iterator_t.  */
           po_message_iterator_free (iterator);
         }

       /* Write back the result.  */
       po_file_t result = po_file_write (file, filename, &handler);
     }

     /* Always release the returned po_file_t.  */
     po_file_free (file);