17.4.5.5 Registrare un processore di output

Un processore di output è l’immagine riflessa di un analizzatore di input. Consente a un’estensione di prendere il controllo dell’output indirizzato verso un file che sia stato aperto con gli operatori di ridirezione di I/O ‘>’ o ‘>>’ (vedi la sezione Ridirigere l’output di print e printf).

Il processore di output è molto simile, come struttura, all’analizzatore di input:

typedef struct awk_output_wrapper {
    const char *nome;   /* nome del processore */
    awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf);
    awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf);
    awk_const struct awk_output_wrapper *awk_const next; /* per gawk */
} awk_output_wrapper_t;

I campi sono i seguenti:

const char *nome;

Questo è il nome del processore di output.

awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf);

Questo è il puntatore a una funzione che esamina l’informazione contenuta nella struttura awk_output_buf_t puntata da outbuf. Dovrebbe restituire true se il processore di output vuole elaborare il file, e false in caso contrario. Nessuno stato (valori di variabili, etc.) dovrebbe essere modificato all’interno di gawk.

awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf);

La funzione puntata da questo campo viene chiamata quando gawk decide di consentire al processore di output di prendere il controllo del file. Dovrebbe riempire in maniera appropriata dei campi nella struttura awk_output_buf_t, come descritto sotto, e restituire true se ha successo, false in caso contrario.

awk_const struct output_wrapper *awk_const next;

Questa struttura è per uso di gawk; per questo motivo è marcata awk_const in modo che l’estensione non possa modificarlo.

La struttura awk_output_buf_t è simile a questa:

typedef struct awk_output_buf {
    const char *nome;   /* nome del file in output */
    const char *modo;   /* argomento mode per fopen */
    FILE *fp;           /* puntatore stdio file */
    awk_bool_t redirected;  /* true se un processore è attivo */
    void *opaque;       /* per uso del processore di output */
    size_t (*gawk_fwrite)(const void *buf, size_t size, size_t count,
                FILE *fp, void *opaque);
    int (*gawk_fflush)(FILE *fp, void *opaque);
    int (*gawk_ferror)(FILE *fp, void *opaque);
    int (*gawk_fclose)(FILE *fp, void *opaque);
} awk_output_buf_t;

Anche qui, l’estensione definirà le funzioni XXX_can_take_file() e XXX_take_control_of() che esaminano e aggiornano campi dati in awk_output_buf_t. I campi dati sono i seguenti:

const char *nome;

Il nome del file in output.

const char *modo;

La stringa mode (come sarebbe usata nel secondo argomento della chiamata di sistema fopen()) con cui il file era stato aperto.

FILE *fp;

Il puntatore FILE da <stdio.h>. gawk apre il file prima di controllare se esiste un processore di output.

awk_bool_t redirected;

Questo campo dev’essere impostato a true dalla funzione XXX_take_control_of().

void *opaque;

Questo puntatore è opaco per gawk. L’estensione dovrebbe usarlo per contenere un puntatore a qualsiasi dato privato associato al file.

size_t (*gawk_fwrite)(const void *buf, size_t size, size_t count,

                      FILE *fp, void *opaque);

int (*gawk_fflush)(FILE *fp, void *opaque);

int (*gawk_ferror)(FILE *fp, void *opaque);

int (*gawk_fclose)(FILE *fp, void *opaque);

Questi puntatori dovrebbero essere impostati per puntare a funzioni la cui azione sia equivalente a quella delle funzioni di <stdio.h>, se questo è cio che si desidera. gawk usa questi puntatori a funzione per tutti gli output. gawk inizializza i puntatori per puntare a funzioni interne “di passaggio” che si limitano a chiamare le funzioni normali di <stdio.h>, e quindi un’estensione deve ridefinire solo le funzioni appropriate per fare il lavoro richiesto.

La funzione XXX_can_take_file() dovrebbe decidere in base ai campi nome e modo, e a ogni altro ulteriore indicatore di stato (p.es., valori di variabili awk) adatto allo scopo.

Quando gawk chiama XXX_take_control_of(), la funzione dovrebbe riempire i rimanenti campi in modo opportuno, tranne che per fp, che dovrebbe essere usato normalmente.

Il processore di output va registrato usando la seguente funzione:

void register_output_wrapper(awk_output_wrapper_t *output_wrapper);

Registra il processore di output puntato da output_wrapper con gawk.