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

gawk: Extension API Boilerplate

 
 16.4.14 Boilerplate Code
 ------------------------
 
 As mentioned earlier (⇒Extension Mechanism Outline), the function
 definitions as presented are really macros.  To use these macros, your
 extension must provide a small amount of boilerplate code (variables and
 functions) toward the top of your source file, using predefined names as
 described here.  The boilerplate needed is also provided in comments in
 the 'gawkapi.h' header file:
 
      /* Boilerplate code: */
      int plugin_is_GPL_compatible;
 
      static gawk_api_t *const api;
      static awk_ext_id_t ext_id;
      static const char *ext_version = NULL; /* or ... = "some string" */
 
      static awk_ext_func_t func_table[] = {
          { "name", do_name, 1, 0, awk_false, NULL },
          /* ... */
      };
 
      /* EITHER: */
 
      static awk_bool_t (*init_func)(void) = NULL;
 
      /* OR: */
 
      static awk_bool_t
      init_my_extension(void)
      {
          ...
      }
 
      static awk_bool_t (*init_func)(void) = init_my_extension;
 
      dl_load_func(func_table, some_name, "name_space_in_quotes")
 
    These variables and functions are as follows:
 
 'int plugin_is_GPL_compatible;'
      This asserts that the extension is compatible with the GNU GPL
      (⇒Copying).  If your extension does not have this, 'gawk'
      will not load it (⇒Plugin License).
 
 'static gawk_api_t *const api;'
      This global 'static' variable should be set to point to the
      'gawk_api_t' pointer that 'gawk' passes to your 'dl_load()'
      function.  This variable is used by all of the macros.
 
 'static awk_ext_id_t ext_id;'
      This global static variable should be set to the 'awk_ext_id_t'
      value that 'gawk' passes to your 'dl_load()' function.  This
      variable is used by all of the macros.
 
 'static const char *ext_version = NULL; /* or ... = "some string" */'
      This global 'static' variable should be set either to 'NULL', or to
      point to a string giving the name and version of your extension.
 
 'static awk_ext_func_t func_table[] = { ... };'
      This is an array of one or more 'awk_ext_func_t' structures, as
      described earlier (⇒Extension Functions).  It can then be
      looped over for multiple calls to 'add_ext_func()'.
 
 'static awk_bool_t (*init_func)(void) = NULL;'
 '                   OR'
 'static awk_bool_t init_my_extension(void) { ... }'
 'static awk_bool_t (*init_func)(void) = init_my_extension;'
      If you need to do some initialization work, you should define a
      function that does it (creates variables, opens files, etc.)  and
      then define the 'init_func' pointer to point to your function.  The
      function should return 'awk_false' upon failure, or 'awk_true' if
      everything goes well.
 
      If you don't need to do any initialization, define the pointer and
      initialize it to 'NULL'.
 
 'dl_load_func(func_table, some_name, "name_space_in_quotes")'
      This macro expands to a 'dl_load()' function that performs all the
      necessary initializations.
 
    The point of all the variables and arrays is to let the 'dl_load()'
 function (from the 'dl_load_func()' macro) do all the standard work.  It
 does the following:
 
   1. Check the API versions.  If the extension major version does not
      match 'gawk''s, or if the extension minor version is greater than
      'gawk''s, it prints a fatal error message and exits.
 
   2. Check the MPFR and GMP versions.  If there is a mismatch, it prints
      a fatal error message and exits.
 
   3. Load the functions defined in 'func_table'.  If any of them fails
      to load, it prints a warning message but continues on.
 
   4. If the 'init_func' pointer is not 'NULL', call the function it
      points to.  If it returns 'awk_false', print a warning message.
 
   5. If 'ext_version' is not 'NULL', register the version string with
      'gawk'.
 
© manpagez.com 2000-2018
Individual documents may contain additional copyright information.