17.4.14 Codice predefinito di interfaccia API

Come già detto (vedi la sezione Una panoramica sul funzionamento ad alto livello), le definizioni di funzioni qui presentate sono in realtà delle macro. Per usare queste macro, l’estensione deve fornire una piccola quantità di codice predefinito (variabili e funzioni) nella parte iniziale del file sorgente, usando dei nomi standard, come descritto qui sotto. Il codice predefinito in questione è anche descritto nel file di intestazione gawkapi.h:

/* Codice predefinito: */
int plugin_is_GPL_compatible;

static gawk_api_t *const api;

static awk_ext_id_t ext_id;
static const char *ext_version = NULL; /* o … = "qualche stringa" */

static awk_ext_func_t func_table[] = {
    { "name", do_name, 1, 0, awk_false, NULL },
    /* … */
};

/* O: */

static awk_bool_t (*init_func)(void) = NULL;

/* OPPURE: */

static awk_bool_t
init_mia_estensione(void)
{
    …
}

static awk_bool_t (*init_func)(void) = init_mia_estensione;

dl_load_func(func_table, qualche_nome, "name_space_in_quotes")

Queste variabili e funzioni sono:

int plugin_is_GPL_compatible;

Qui si dichiara che l’estensione è compatibile con la licenza GNU GPL (vedi la sezione Licenza Pubblica Generale GNU (GPL)).

Se l’estensione non ha questa variabile, non verrà caricata da gawk (vedi la sezione Tipo di licenza delle estensioni).

static gawk_api_t *const api;

Questa variabile globale static dovrebbe essere impostata per puntare al puntatore gawk_api_t che gawk passa alla funzione (dell’estensione) dl_load(). Questa variabile è usata da tutte le macro.

static awk_ext_id_t ext_id;

Questa variabile globale static dovrebbe essere impostata al valore awk_ext_id_t che gawk passa alla funzione dl_load(). Questa variabile è usata da tutte le macro.

static const char *ext_version = NULL; /* o … = "qualche stringa" */

Questa variabile globale static dovrebbe essere impostata a NULL oppure puntare a una stringa che contiene il nome e la versione dell’estensione.

static awk_ext_func_t func_table[] = { … };

Questo è un vettore di una o più strutture awk_ext_func_t, come descritto in precedenza (vedi la sezione Registrare funzioni di estensione). Può essere usato in seguito per più chiamate a add_ext_func().

static awk_bool_t (*init_func)(void) = NULL;

                   OR

static awk_bool_t init_mia_estensione(void) { … }

static awk_bool_t (*init_func)(void) = init_mia_estensione;

Se qualche lavoro di inizializzazione è necessario, si dovrebbe definire una funzione all’uopo (crea variabili, apre file, etc.) e poi definire il puntatore init_func che punti alla funzione stessa. La funzione dovrebbe restituire awk_false se non va a buon fine o awktrue se tutto va bene.

Se un’inizializzazione non è necessaria, si definisca il puntatore e lo si inizializzi a NULL.

dl_load_func(func_table, qualche_nome, "nome_spazio_tra_doppi_apici")

Questa macro genera una funzione dl_load() che farà tutte le inizializzazioni necessarie.

Lo scopo di tutte le variabili e dei vettori è di far sì che la funzione dl_load() (richiamata dalla macro dl_load_func()) faccia tutto il lavoro standard necessario, qui descritto:

1. Controlla le versioni dell’API. Se la versione principale dell’estensione non corrisponde a quella di gawk o se la versione secondaria dell’estensione è maggiore di quella di gawk, stampa un messaggio di errore fatale ed esce.
2. Controlla le versioni di MPFR e GMP. Se non sono allo stesso livello con quelle in uso localmente, stampa un messaggio di errore fatale ed esce.
3. Carica le funzioni definite in func_table. Se qualche caricamento non riesce, stampa un messaggio di avvertimento ma continua l’esecuzione.
4. Se il puntatore init_func non è NULL, chiama la funzione da esso puntata. Se questa restituisce awk_false, stampa un messaggio di avvertimento.
5. Se ext_version non è NULL, registra la stringa di versione con gawk.