17.4.5.6 Customized Two-way Processors

A two-way processor combines an input parser and an output wrapper for two-way I/O with the ‘|&’ operator (see section Redirecting Output of print and printf). It makes identical use of the awk_input_parser_t and awk_output_buf_t structures as described earlier.

A two-way processor is represented by the following structure:

typedef struct awk_two_way_processor {
    const char *name;   /* name of the two-way processor */
    awk_bool_t (*can_take_two_way)(const char *name);
    awk_bool_t (*take_control_of)(const char *name,
                                  awk_input_buf_t *inbuf,
                                  awk_output_buf_t *outbuf);
    awk_const struct awk_two_way_processor *awk_const next;  /* for gawk */
} awk_two_way_processor_t;

The fields are as follows:

const char *name;

The name of the two-way processor.

awk_bool_t (*can_take_two_way)(const char *name);

The function pointed to by this field should return true if it wants to take over two-way I/O for this file name. It should not change any state (variable values, etc.) within gawk.

awk_bool_t (*take_control_of)(const char *name,

                              awk_input_buf_t *inbuf,

                              awk_output_buf_t *outbuf);

The function pointed to by this field should fill in the awk_input_buf_t and awk_output_buf_t structures pointed to by inbuf and outbuf, respectively. These structures were described earlier.

awk_const struct two_way_processor *awk_const next;

This is for use by gawk; therefore it is marked awk_const so that the extension cannot modify it.

As with the input parser and output processor, you provide “yes I can take this” and “take over for this” functions, XXX_can_take_two_way() and XXX_take_control_of().

You register your two-way processor with the following function:

void register_two_way_processor(awk_two_way_processor_t *two_way_processor);

Register the two-way processor pointed to by two_way_processor with gawk.