17.4.1 Introduzione alle funzioni dell’API

L’accesso a funzionalità interne a gawk è effettuato con una chiamata che usa i puntatori a funzione resi disponibili all’estensione.

Puntatori a funzioni API sono previsti per i seguenti tipi di operazioni:

• Allocare, riallocare e liberare memoria.
• Registrare funzioni. Si possono registrare:
  • - Funzioni di estensione
  • - Funzioni ausiliarie di pulizia (callbacks)
  • - Una stringa di caratteri che identifica la versione
  • - Funzioni per analizzare l’input
  • - Funzioni per modificare l’output
  • - Processori bidirezionali

  Tutti questi elementi sono spiegati dettagliatamente nel resto di questo capitolo.

• Stampare messaggi fatali, di avvertimento e quelli generati dall’opzione “lint”.
• Modificare ERRNO o annullarne il valore.
• Accedere a parametri, compresa la possibilità di definire come vettore un parametro ancora indefinito.
• Accedere alla "tabella dei simboli": procurarsi il valore di una variabile globale, crearne una nuova o modificarne una già esistente.
• Creare ed eliminare valori nascosti; ciò rende possibile usare un particolare valore per più di una variabile, e può migliorare parecchio le prestazioni.
• Manipolare vettori:
  • - Ritrovare il valore di elementi del vettore, aggiungerne di nuovi, cancellare e modificare elementi esistenti.
  • - Ottenere il numero di elementi presenti in un vettore
  • - Creare un nuovo vettore
  • - Cancellare un intero vettore
  • - Appiattire un vettore per poter facilmente eseguire un ciclo, in stile C, su tutti i suoi indici ed elementi
• Accedere a ridirezioni e manipolarle.

Alcune osservazioni riguardo all’uso dell’API:

• I seguenti tipi di variabili, macro e/o funzioni sono resi disponibili nel file gawkapi.h. Perché siano utilizzabili, i rispettivi file di intestazione standard indicati devono essere stati specificati prima di includere gawkapi.h. La lista delle macro e dei relativi file di intestazioni è contenuta in Tabella 17.1.

  Elemento C	File d’intestazione
  EOF	<stdio.h>
  valori di errno	<errno.h>
  FILE	<stdio.h>
  NULL	<stddef.h>
  memcpy()	<string.h>
  memset()	<string.h>
  size_t	<sys/types.h>
  struct stat	<sys/stat.h>

  Tabella 17.1: File di intestazioni standard usati nell’API

  Per ragioni di portabilità, specialmente per sistemi che non sono interamente aderenti agli standard, occorre assicurarsi di includere i file corretti nel modo corretto. Questa richiesta mira a mantenere il file gawkapi.h ordinato, invece che farlo diventare un’accozzaglia di problemi di portabilità, quale si può vedere in alcune parti del codice sorgente di gawk.

• Se l’estensione usa le funzionalità MPFR, e si desidera ricevere valori numerici di precisione arbitraria da gawk e/o passare ad esso tali valori, si deve includere l’intestazione <mpfr.h> prima di includere <gawkapi.h>.
• Il file gawkapi.h può essere incluso più volte, senza conseguenze negative. Tuttavia sarebbe meglio evitare di farlo, per uno stile di programmazione migliore.
• Sebbene l’API usi solo funzionalità ISO C 90, c’è un’eccezione; le funzione “costruttrici” usano la parola chiave inline. Se il compilatore in uso non supporta questa parola chiave, si dovrebbe specificare sulla riga di comando il parametro ‘-Dinline=''’ oppure usare gli strumenti Autotools GNU e includere un file config.h nel codice sorgente delle estensioni.
• Tutti i puntatori messi a disposizione da gawk puntano ad aree di memoria gestite da gawk e dovrebbero essere trattati dall’estensione come in sola lettura. Le aree di memoria che contengono tutte le stringhe passate a gawk dall’estensione devono provenire da una chiamata a gawk_malloc(), gawk_calloc() o gawk_realloc(), e sono gestite da gawk da quel punto in avanti.
• L’API definisce parecchie semplici strutture struct che mappano dei valori come sono visti da awk. Un valore può essere un numero double (in virgola mobile, in doppia precisione), una stringa o un vettore (come è il caso per i vettori multidimensionali o nella creazione di un nuovo vettore).

  I valori di tipo stringa sono costituiti da un puntatore e da una lunghezza, poiché nella stringa possono essere presenti dei caratteri NUL (zeri binari, che normalmente marcano la fine di una stringa).

  NOTA: Di proposito, gawk immagazzina le stringhe usando la codifica multibyte correntemente in uso (come definita dalle variabili d’ambiente LC_xxx) e non usando dei caratteri larghi (ovvero due byte per ogni carattere). Ciò riflette il modo con cui gawk memorizza le stringhe internamente, e anche il modo in cui i caratteri sono verosimilmente letti dai file in input e scritti nei file in output.

  NOTA: I valori di una stringa passati a un’estensione da gawk hanno sempre un carattere NUL alla fine (come delimitatore). Quindi è possibile usare senza inconvenienti tali valori di stringa per chiamare funzioni di libreria standard e routine di sistema. Tuttavia, poiché gawk consente che all’interno di una stringa di dati possano essere presenti caratteri NUL, si dovrebbe controllare che la lunghezza di ogni stringa passata un’estensione coincida con il valore restituito dalla funzione strlen() per la stringa stessa.

• Per ottenere un valore (p.es. quello di un parametro o quello di una variabile globale, oppure di un elemento di un vettore), l’estensione chiede un tipo specifico di variabile (numero, stringa, scalare, value cookie [si veda più avanti], vettore o “undefined”). Quando la richiesta è “undefined,” il valore restituito sarà quello originale della variabile in questione.

  In ogni caso, se la richiesta e il tipo effettivo della variabile non corrispondono, la funzione di accesso restituisce “false” e fornisce il tipo proprio della variabile, in modo che l’estensione possa, p.es., stampare un messaggio di errore (del tipo “ricevuto uno scalare, invece del vettore previsto”).

Si possono chiamare le funzioni dell’API usando i puntatori a funzione direttamente, ma l’interfaccia non è molto elegante. Per permettere al codice sorgente delle estensioni di assomigliare di più a un codice normale, il file di intestazione gawkapi.h definisce parecchie macro da usare nel codice sorgente dell’estensione. Questa sezione presenta le macro come se si trattasse di funzioni.