EXPLODE(5)                                                          EXPLODE(5)



NAME
       explode - file format for MICE archives

DESCRIPTION
       A  MICE  libraryor  family  is  the  most general form of an algorithm.
       Unlike a run-time configured routine, like qsort(3), a MICE  family  is
       configured via compile time macros: thus no efficiency or functionality
       is lost due to a "bad fit".  MICE families come packaged in two  files:
       a large source file and a small header file.

       See explode(1l) for a complete description explode's usage.

       Explode  directives  are  hidden from the native processor (viz.  the C
       compiler or mkcmd) in in-line comments.  An escape  sequence  including
       the  native  comment  introducer  and  some  additional noise activates
       explode as it scans the input file.  The delimiter is spelled backwards
       on the end of the line as a sanity check.

       Lexically  explode  looks  at  each source line as a potential command.
       Only treating the input line as a command when  it  finds  the  in-line
       comment sequence followed by a directive.  Directives may have a single
       parameter.  When this parameter is a string it is quoted by  the  first
       non-space character after the directive keyword.

       Most  commonly  a  C source file will only contain a few explode direc-
       tives:
              /*@Header@*/
              #include <stdio.h>
              #include "me.h"
              #include "my_config.h"

              /*@Insert `extern int global_variable;`@*/

              /*@Explode routine1@*/
              /*@Message "globals are in routine1"@*/
              int global_variable;
              int
              routine1()
              {
                   ...
              }

              /*@Explode routine2@*/
              int
              routine2()
              {
              }

DIRECTIVES
       /*@Message %This package requires the header file "tool_cfg.h".%@*/
              Notify the user that the package requires a special header file.

       /*@Header@*/
              Divert  the  following lines to the common prologue for all mod-
              ules.

       /*@Shell %echo "/* this was extracted on `date` by ${NAME-${USER-${LOGNAME-root}}} *""/"%@*/
              Insert the date of extraction into the correct  file.   This  is
              normally done only once in each Header section.

       /*@Insert %extern int errno;%@*/
              Add a declaration for errno to this module.

       /*@Explode gen@*/
              Copy  the  current  Header  to the "gen" module, begin diverting
              text to that module.

       /*@Remove@*/
              Remove documentation or example usage from the file.  (Divert to
              /dev/null.)

       /*@Append gen@*/
              Redivert text to the "gen" module.

       /*@Version: $Revision:... @*/
              Provide a version header for -t option.

       c@Explode regress@c
              A FORTRAN explode directive.

CULTURE
       Most  of  the modules included in the MICE archive are coded by a small
       group of NPC Guild pundits.  All these pundits follow a few naming  and
       format rules that make their code look similar in shape and style.

Variable names and Paints
       Most  variable  names  start with a paint which describes the variables
       type (maybe not all the type, just the smell).  The  rules  for  paints
       are described on the painted types Web page.

Layout of the code
       A  MICE  archive  is broken into sections by convention and by explode.
       The first section has stuff in it that describes  the  archive  itself,
       its  version, its mk marked lines, or some comments about the usage and
       history of the part [citations for the algorithms used].

       That section ends with the explode directive Header.  The header itself
       begins  with  a  notice  that  the  extracted  part is not to be edited
       because the real source is the whole part (which is version  controlled
       as a unit)!

       Each  subsequent section is one of the other explode hunks.  Each func-
       tion that might stand on its own is broken into a separate file.   Some
       functions  are  combined  into  a  single file (for example if they are
       mutually recursive).

       The last hunk in the file is usually a test driver.   Here  is  the  an
       example driver boiler plate:
              /*@Remove@*/
              #if defined(TEST)

              /*@Explode main@*/

              char *progname = "pkgname-main";

              int
              main(argc, argv)
              {
                   main function
              }
              /*@Remove@*/
              #endif /* test driver */

AUTHOR
       Kevin Braunsdorf, NPC Guild.org
       mkcmd atspam-filter ksb dot npcguild.org

       This  is a modification of the code the author wrote at Purdue.  Purdue
       has no (stated) interest in this software anymore.

SEE ALSO
       explode(1l), mkcmd(1l), sh(1), mk(1l)



                                     LOCAL                          EXPLODE(5)

NAME | DESCRIPTION | DIRECTIVES | CULTURE | Variable names and Paints | Layout of the code | AUTHOR | SEE ALSO