AnjutaAutogen: Anjuta Developers Reference Manual

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*AnjutaAutogenFunc) ()
void | (*AnjutaAutogenOutputFunc) ()
AnjutaAutogen * | anjuta_autogen_new ()
gboolean | anjuta_autogen_write_definition_file ()
void | anjuta_autogen_set_library_path ()
void | anjuta_autogen_clear_library_path ()
GList * | anjuta_autogen_get_library_paths ()
gboolean | anjuta_autogen_set_input_file ()
gboolean | anjuta_autogen_set_output_file ()
gboolean | anjuta_autogen_set_output_callback ()
gboolean | anjuta_autogen_execute ()
gboolean | anjuta_check_autogen ()

## Types and Values

| AnjutaAutogen

## Object Hierarchy

        GObject
        ╰── AnjutaAutogen

## Includes

    #include <libanjuta/anjuta-autogen.h>

## 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.

## Functions

### AnjutaAutogenFunc ()

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

This function is called when the autogen process is completed.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

### AnjutaAutogen

    typedef struct _AnjutaAutogen AnjutaAutogen;

A GObject wrapper for running GNU autogen.

## See Also

AnjutaLauncher