17.4.5.1 Registrare funzioni di estensione

Le funzioni di estensione sono descritte dal seguente tracciato record:

typedef struct awk_ext_func {
    const char *nome;
    awk_value_t *(*const function)(int num_actual_args,
                                   awk_value_t *risultato,
                                   struct awk_ext_func *finfo);
    const size_t max_expected_args;
    const size_t min_required_args;
    awk_bool_t suppress_lint;
    void *data;        /* puntatore di tipo opaco
                       a ogni informazione ulteriore */
} awk_ext_func_t;

I campi sono:

const char *nome;

Il nome della nuova funzione. Il codice sorgente a livello di awk richiama la funzione usando questo nome. Il nome è una normale stringa di caratteri del linguaggio C.

I nomi di funzione devono rispettare le stesse regole che valgono per gli identificativi awk. Cioè, devono iniziare o con una lettera dell’alfabeto inglese o con un trattino basso, che possono essere seguiti da un numero qualsiasi di lettere, cifre o trattini bassi. L’uso di maiuscolo/minuscolo è significativo.

awk_value_t *(*const function)(int num_actual_args,

                              awk_value_t *risultato,

                              struct awk_ext_func *finfo);

Questo è un puntatore alla funzione C che fornisce la funzionalità per cui è stata scritta l’estensione. La funzione deve riempire l’area di memoria puntata da *risultato con un numero, con una stringa, oppure con una regexp. gawk diventa il proprietario di tutte le stringhe di memoria. Come già detto sopra, la stringa di memoria deve essere stata ottenuta usando gawk_malloc(), gawk_calloc() o gawk_realloc().

L’argomento num_actual_args dice alla funzione scritta in C quanti parametri sono stati effettivamente passati dal codice chiamante all’interno di awk.

La funzione deve restituire il valore di risultato. Questo è per utilità del codice chiamante all’interno di gawk.

size_t max_expected_args;

Questo è il massimo numero di argomenti che la funzione si aspetta di ricevere. Se chiamata con un numero di argomenti maggiore di questo, e se è stato richiesto il controllo lint, gawk stampa un messaggio di avvertimento. Per ulteriori informazioni, si veda la descrizione di suppress_lint, più avanti in questa lista.

const size_t min_required_args;

Questo è il minimo numero di argomenti che la funzione si aspetta di ricevere. Se è chiamata con un numero inferiore di argomenti, gawk stampa un messaggio di errore fatale ed esce.

awk_bool_t suppress_lint;

Questo flag dice a gawk di non stampare un messaggio lint se è stato richiesto un controllo lint e se sono stati forniti più argomenti di quelli attesi. Una funzione di estensione può stabilire se gawk ha già stampato almeno uno di tali messaggi controllando se ‘num_actual_args > finfo->max_expected_args’. In tal caso, se la funzione non desidera la stampa di ulteriori messaggi, dovrebbe impostare finfo->suppress_lint a awk_true.

void *data;

Questo è un puntatore di tipo opaco a tutti quei dati che una funzione di estensione desidera avere disponibili al momento della chiamata. Passando alla funzione di estensione la struttura awk_ext_func_t e avendo al suo interno questo puntatore disponibile, rende possibile scrivere un’unica funzione C o C++ che implementa più di una funzione di estensione a livello awk.

Una volta preparato un record che descrive l’estensione, la funzione di estensione va registrata con gawk usando questa funzione dell’API:

awk_bool_t add_ext_func(const char *name_space, awk_ext_func_t *func);

Questa funzione restituisce il valore true se ha successo, oppure false in caso contrario. Il parametro name_space indica lo spazio-dei-nomi in cui porre la funzione (vedi la sezione Spazi-dei-nomi in gawk). Si usi una stringa vuota ("") o "awk" per porre la funzione nello spazio-dei-nomi awk, che è quello di default. Il puntatore func è l’indirizzo di una struttura struct che rappresenta la funzione stessa, come descritto sopra.

gawk non modifica ciò che è puntato da func, ma la funzione di estensione stessa riceve questo puntatore e può modificarlo e farlo puntare altrove, quindi il puntatore non è stato dichiarato di tipo costante (const).

La combinazione di min_required_args, max_expected_args, e suppress_lint può ingenerare confusione. Ecco delle linee-guida sul da farsi.

Un numero qualsiasi di argomenti è valido

Impostare min_required_args and max_expected_args a zero e impostare suppress_lint ad awk_true.

Un numero minimo di argomenti è richiesto, ma non c’è un limite al numero massimo

Impostare min_required_args al minimo richiesto. Impostare max_expected_args a zero e impostare suppress_lint ad awk_true.

Un numero minino di argomenti è richiesto, ma c’è un limite al numero massimo

Impostare min_required_args al minimo richiesto. Impostare max_expected_args al massimo atteso. Impostare suppress_lint ad awk_false.

Un numero minino di argomenti è richiesto, ma c’è un numero massimo non superabile

Impostare min_required_args al minimo richiesto. Impostare max_expected_args al massimo atteso. Impostare suppress_lint ad awk_false. Nella funzione di estensione, controllare che num_actual_args non ecceda f->max_expected_args. Se il massimo è superato, stampare un messaggio di errore fatale.