manpagez: man pages & more
info gawk
Home | html | info | man

gawk: Extension Functions

 
 16.4.5.1 Registering An Extension Function
 ..........................................
 
 Extension functions are described by the following record:
 
      typedef struct awk_ext_func {
          const char *name;
          awk_value_t *(*const function)(int num_actual_args,
                                         awk_value_t *result,
                                         struct awk_ext_func *finfo);
          const size_t max_expected_args;
          const size_t min_required_args;
          awk_bool_t suppress_lint;
          void *data;        /* opaque pointer to any extra state */
      } awk_ext_func_t;
 
    The fields are:
 
 'const char *name;'
      The name of the new function.  'awk'-level code calls the function
      by this name.  This is a regular C string.
 
      Function names must obey the rules for 'awk' identifiers.  That is,
      they must begin with either an English letter or an underscore,
      which may be followed by any number of letters, digits, and
      underscores.  Letter case in function names is significant.
 
 'awk_value_t *(*const function)(int num_actual_args,'
 '                              awk_value_t *result,'
 '                              struct awk_ext_func *finfo);'
      This is a pointer to the C function that provides the extension's
      functionality.  The function must fill in '*result' with either a
      number, a string, or a regexp.  'gawk' takes ownership of any
      string memory.  As mentioned earlier, string memory _must_ come
      from one of 'gawk_malloc()', 'gawk_calloc()', or 'gawk_realloc()'.
 
      The 'num_actual_args' argument tells the C function how many actual
      parameters were passed from the calling 'awk' code.
 
      The 'finfo' parameter is a pointer to the 'awk_ext_func_t' for this
      function.  The called function may access data within it as
      desired, or not.
 
      The function must return the value of 'result'.  This is for the
      convenience of the calling code inside 'gawk'.
 
 'const size_t max_expected_args;'
      This is the maximum number of arguments the function expects to
      receive.  If called with more arguments than this, and if lint
      checking has been enabled, then 'gawk' prints a warning message.
      For more information, see the entry for 'suppress_lint', later in
      this list.
 
 'const size_t min_required_args;'
      This is the minimum number of arguments the function expects to
      receive.  If called with fewer arguments, 'gawk' prints a fatal
      error message and exits.
 
 'awk_bool_t suppress_lint;'
      This flag tells 'gawk' not to print a lint message if lint checking
      has been enabled and if more arguments were supplied in the call
      than expected.  An extension function can tell if 'gawk' already
      printed at least one such message by checking if 'num_actual_args >
      finfo->max_expected_args'.  If so, and the function does not want
      more lint messages to be printed, it should set
      'finfo->suppress_lint' to 'awk_true'.
 
 'void *data;'
      This is an opaque pointer to any data that an extension function
      may wish to have available when called.  Passing the
      'awk_ext_func_t' structure to the extension function, and having
      this pointer available in it enable writing a single C or C++
      function that implements multiple 'awk'-level extension functions.
 
    Once you have a record representing your extension function, you
 register it with 'gawk' using this API function:
 
 'awk_bool_t add_ext_func(const char *name_space, awk_ext_func_t *func);'
      This function returns true upon success, false otherwise.  The
      'name_space' parameter is currently not used; you should pass in an
      empty string ('""').  The 'func' pointer is the address of a
      'struct' representing your function, as just described.
 
      'gawk' does not modify what 'func' points to, but the extension
      function itself receives this pointer and can modify what it points
      to, thus it is purposely not declared to be 'const'.
 
    The combination of 'min_required_args', 'max_expected_args', and
 'suppress_lint' may be confusing.  Here is how you should set things up.
 
 Any number of arguments is valid
      Set 'min_required_args' and 'max_expected_args' to zero and set
      'suppress_lint' to 'awk_true'.
 
 A minimum number of arguments is required, no limit on maximum number of arguments
      Set 'min_required_args' to the minimum required.  Set
      'max_expected_args' to zero and set 'suppress_lint' to 'awk_true'.
 
 A minimum number of arguments is required, a maximum number is expected
      Set 'min_required_args' to the minimum required.  Set
      'max_expected_args' to the maximum expected.  Set 'suppress_lint'
      to 'awk_false'.
 
 A minimum number of arguments is required, and no more than a maximum is allowed
      Set 'min_required_args' to the minimum required.  Set
      'max_expected_args' to the maximum expected.  Set 'suppress_lint'
      to 'awk_false'.  In your extension function, check that
      'num_actual_args' does not exceed 'f->max_expected_args'.  If it
      does, issue a fatal error message.
 
© manpagez.com 2000-2018
Individual documents may contain additional copyright information.