AnjutaAutogen

## AnjutaAutogen AnjutaAutogen — Template engine using GNU autogen program. |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libanjuta/anjuta-autogen.h>

    void                (*AnjutaAutogenFunc)                (AnjutaAutogen *autogen,
                                                             gpointer data);
    void                (*AnjutaAutogenOutputFunc)          (const gchar *output,
                                                             gpointer data);
    AnjutaAutogen *     anjuta_autogen_new                  (void);
    gboolean            anjuta_autogen_write_definition_file
                                                            (AnjutaAutogen *this,
                                                             GHashTable *values,
                                                             GError **error);
    void                anjuta_autogen_set_library_path     (AnjutaAutogen *this,
                                                             const gchar *directory);
    void                anjuta_autogen_clear_library_path   (AnjutaAutogen *this);
    GList *             anjuta_autogen_get_library_paths    (AnjutaAutogen *this);
    gboolean            anjuta_autogen_set_input_file       (AnjutaAutogen *this,
                                                             const gchar *filename,
                                                             const gchar *start_marker,
                                                             const gchar *end_marker);
    gboolean            anjuta_autogen_set_output_file      (AnjutaAutogen *this,
                                                             const gchar *filename);
    gboolean            anjuta_autogen_set_output_callback  (AnjutaAutogen *this,
                                                             AnjutaAutogenOutputFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);
    gboolean            anjuta_autogen_execute              (AnjutaAutogen *this,
                                                             AnjutaAutogenFunc func,
                                                             gpointer data,
                                                             GError **error);
    gboolean            anjuta_check_autogen                (void);
                        AnjutaAutogenClass;
                        AnjutaAutogen;

## Object Hierarchy

      GObject
       +----AnjutaAutogen

## Description

GNU autogen is a program generating a text file from a template and a definition file. The template contains fixed text and variables those will be replaced under the control of the definition file.

By example from the following definition file

    AutoGen Definitions .;
    list = { list_element = alpha;
             list_info    = "some alpha stuff"; };
    list = { list_info    = "more beta stuff";
             list_element = beta; };
    list = { list_element = omega;
             list_info    = "final omega stuff"; }

And the following template

    [+ AutoGen5 template +]
    typedef enum {[+
       FOR list "," +]
            IDX_[+ (string-upcase! (get "list_element")) +][+
       ENDFOR list +] }  list_enum;

Autogen generates

    typedef enum {
            IDX_ALPHA,
            IDX_BETA,
            IDX_OMEGA }  list_enum;

The template file can be quite complex, you can read autogen documentation here.

The AnjutaAutogen object takes care of writing the definition file from a hash table and call autogen. The output can be written in a file or passed to a callback function. Autogen is executed asynchronously, so there is another callback function called when the processing is completed.

## Details

### AnjutaAutogenFunc ()

    void                (*AnjutaAutogenFunc)                (AnjutaAutogen *autogen,
                                                             gpointer data);

This function is called when the autogen process is completed.

`autogen` : | AnjutaAutogen object.
`data` : | user data passed to the callback.

### AnjutaAutogenOutputFunc ()

    void                (*AnjutaAutogenOutputFunc)          (const gchar *output,
                                                             gpointer data);

This function is called each time there is new data from autogen.

`output` : | data generated by autogen.
`data` : | user data passed to the callback.

### anjuta_autogen_new ()

    AnjutaAutogen *     anjuta_autogen_new                  (void);

Create a new autogen object.

Returns : | A new AnjutaAutogen object. Free it using g_object_unref. [transfer full]

### anjuta_autogen_write_definition_file ()

    gboolean            anjuta_autogen_write_definition_file
                                                            (AnjutaAutogen *this,
                                                             GHashTable *values,
                                                             GError **error);

Write the autogen definition file. The definition file defined variables those will be used, typically replaced, in the template files.

The hash table keys are the names of the variables. The name can include an index in square bracket, by example "members[0]". All values are strings but but they could include children using braces, by example "{count=2; list="aa bb"}".

The file is created in a temporary directory and removed when the object is destroyed.

`this` : | A AnjutaAutogen object
`values` : | A hash table containing all definitions. [element-type utf8 utf8]
`error` : | Error propagation and reporting
Returns : | `TRUE` if the file has been written without error,

### anjuta_autogen_set_library_path ()

    void                anjuta_autogen_set_library_path     (AnjutaAutogen *this,
                                                             const gchar *directory);

Add a new directory in the list of autogen libraries path.

Autogen can include files. These included file will be searched by default in the same directory than the template file. This functions allows you to add other directories.

`this` : | A AnjutaAutogen object
`directory` : | A path containing autogen library.

### anjuta_autogen_clear_library_path ()

    void                anjuta_autogen_clear_library_path   (AnjutaAutogen *this);

Remove all library pathes.

`this` : | A AnjutaAutogen object

### anjuta_autogen_get_library_paths ()

    GList *             anjuta_autogen_get_library_paths    (AnjutaAutogen *this);

Get the list of all directories searched for files included in the autogen templates.

`this` : | A AnjutaAutogen object
Returns : | A list of directories. The content and the list itself are owned by the AnjutaAutogen object and should not be modified or freed. [element-type gchar*][transfer none]

### anjuta_autogen_set_input_file ()

    gboolean            anjuta_autogen_set_input_file       (AnjutaAutogen *this,
                                                             const gchar *filename,
                                                             const gchar *start_marker,
                                                             const gchar *end_marker);

Read an autogen template file, optionally adding autogen markers.

To be recognized as an autogen template, the first line has to contain:

- the start marker

- "autogen5 template"

- the end marker

These markers are a custom sequence of up to 7 characters delimiting the start and the end of autogen variables and macros.

This function can add this line using the value of `start_marker` and `end_marker`. If this line is already present in the file, `start_marker` and `end_marker` must be `NULL`.

`this` : | A AnjutaAutogen object
`filename` : | name of the input template file
`start_marker` : | start marker string. [allow-none]
`end_marker` : | end marker string. [allow-none]
Returns : | `TRUE` if the file has been read without error.

### anjuta_autogen_set_output_file ()

    gboolean            anjuta_autogen_set_output_file      (AnjutaAutogen *this,
                                                             const gchar *filename);

Define the name of the generated file.

`this` : | A AnjutaAutogen object
`filename` : | name of the generated file
Returns : | `TRUE` if the file has been set without error.

### anjuta_autogen_set_output_callback ()

    gboolean            anjuta_autogen_set_output_callback  (AnjutaAutogen *this,
                                                             AnjutaAutogenOutputFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy);

Define that autogen output should be send to a function as soon as it arrives.

`this` : | A AnjutaAutogen object
`func` : | Function call each time we get new data from autogen
`user_data` : | User data to pass to `func`, or `NULL`. [allow-none]
`destroy` : | Function call when the process is complete to free user data
Returns : | `TRUE` if there is no error.

### anjuta_autogen_execute ()

    gboolean            anjuta_autogen_execute              (AnjutaAutogen *this,
                                                             AnjutaAutogenFunc func,
                                                             gpointer data,
                                                             GError **error);

Asynchronously execute autogen to generate the output, calling `func` when the process is completed.

`this` : | A AnjutaAutogen object
`func` : | A function called when autogen is terminated. [scope async][allow-none]
`data` : | User data to pass to `func`, or `NULL`. [allow-none]
`error` : | Error propagation and reporting. [allow-none]
Returns : | `TRUE` if the file has been processed without error.

### anjuta_check_autogen ()

    gboolean            anjuta_check_autogen                (void);

Check if autogen version 5 is installed.

Returns : | `TRUE` if autogen is installed.

### AnjutaAutogenClass

    typedef struct _AnjutaAutogenClass AnjutaAutogenClass;

### AnjutaAutogen

    typedef struct _AnjutaAutogen AnjutaAutogen;

A GObject wrapper for running GNU autogen.

## See Also

AnjutaLauncher