GAWK: Effective AWK Programming

288 GAWK: Effective AWK ProgrammingWith the disclaimers out of the way, the following types, structure members, functions,and macros are declared in ‘awk.h’ and are of use when writing extensions. The next sectionshows how they are used:AWKNUMNODEAn AWKNUM is the internal type of awk floating-point numbers. Typically, it is aC double.Just about everything is done using objects of type NODE. These contain bothstrings and numbers, as well as variables and arrays.AWKNUM force_number(NODE *n)This macro forces a value to be numeric. It returns the actual numeric valuecontained in the node. It may end up calling an internal gawk function.void force_string(NODE *n)This macro guarantees that a NODE’s string value is current. It may end upcalling an internal gawk function. It also guarantees that the string is zeroterminated.size_t get_curfunc_arg_count(void)This function returns the actual number of parameters passed to the currentfunction. Inside the code of an extension this can be used to determine the maximumindex which is safe to use with stack_ptr. If this value is greater thantree->param_cnt, the function was called incorrectly from the awk program.Caution: This function is new as of gawk 3.1.4.n->param_cntInside an extension function, this is the maximum number of expected parameters,as set by the make_builtin function.n->stptrn->stlenn->typen->vnameThe data and length of a NODE’s string value, respectively. The string is notguaranteed to be zero-terminated. If you need to pass the string value to a Clibrary function, save the value in n->stptr[n->stlen], assign ’\0’ to it, callthe routine, and then restore the value.The type of the NODE. This is a C enum. Values should be either Node_var orNode_var_array for function parameters.The “variable name” of a node. This is not of much use inside externally writtenextensions.void assoc_clear(NODE *n)Clears the associative array pointed to by n. Make sure that ‘n->type ==Node_var_array’ first.NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference)Finds, and installs if necessary, array elements. symbol is the array, subs isthe subscript. This is usually a value created with tmp_string (see below).reference should be TRUE if it is an error to use the value before it is created.Typically, FALSE is the correct value to use from extension functions.