engine.h

   1 #ifndef _ENGINE_H_
   2 #define _ENGINE_H_
   3
   4 #include <stdio.h>
   5
   6 /* This function is intended to be an interface that all engines
   7  * implement, so that a programmer (you) can implement a ruleset for a
   8  * CA-like system by simply implementing these functions, then linking
   9  * the result against a driver (e.g. the sample driver defined by
  10  * driver.c). These functions SHALL return 0 for success, a nonzero
  11  * value for failure. If this value is passed to con_errstring it
  12  * SHOULD result in a useful error string.
  13  *
  14  * The engine can expect a driver flow of:
  15  *
  16  * - exactly one call of con_initialize_f | con_initialize_wh
  17  *
  18  * - any calls to any functions except con_initialize_f,
  19  *   con_initialize_wh, con_teardown
  20  *
  21  * - exactly one call of con_teardown
  22  *
  23  * Any other flow
  24  */
  25
  26 /* Initialization routines. Read in from a file (which should be some
  27  * kind of meaningful encoding, perhaps particular to the engine) or
  28  * simply initialize empty[*] on a rectangular grid.
  29  *
  30  * * ``Why do you close your eyes?'' Sussman asked his teacher.  ``So
  31  *   that the room will be empty.'' replied Minsky.
  32  */
  33 int con_initialize_f(FILE * ifp);
  34 int con_initialize_wh(int width, int height);
  35
  36 /* Get the dimensions of the game. These should return consistent
  37  * values once an initialization has occured
  38  */
  39 int con_width(void);
  40 int con_height(void);
  41
  42 /* Take another step in the simulation */
  43 int con_step(void);
  44
  45 /* Set *rep such that *rep is the null-terminated string for
  46  * display . It is the engine's responsibility to handle allocation
  47  * and cleanup for the internal representation returned. Any con_ call
  48  * invalidates the data returned by con_representation.
  49  *
  50  * Note: The out parameter is a char *, not a char, so that engines
  51  * can return smiley faces and dromedary camels and all that jazz.
  52  */
  53 int con_rep_at(int x, int y, const char ** const rep);
  54
  55 /* Set *n, *titles such that *titles is an array of *n null-terminated
  56  * strings representing the names of different values that would need
  57  * to be provided in order to re-define an arbitrary cell.
  58  *
  59  * Standard Conway's Game of Life rules might, for example, set *n to
  60  * 1 and *titles to { "Alive?" }. This presentation form is for
  61  * engines that internally represent more complicated objects.
  62  *
  63  * This method SHALL set *n and *titles consistantly once an
  64  * initialization method is called
  65  */
  66 int con_input_titles(int * const n, const char * const ** const titles);
  67
  68 /* Given an array of null-terminated strings (where it is the driver's
  69  * responsibility to ensure that the length of vals is equal to the
  70  * value which *n is set to in con_input_titles), set the cell at x, y
  71  * to represent those values
  72  */
  73 int con_set_val(int x, int y, const char ** vals);
  74
  75 /* Clean up all internal resources. Any con_ call after con_teardown
  76  * is undefined.
  77  */
  78 int con_teardown(void);
  79
  80 /* If a suitably complex error detection system is in place in the
  81  * engine, this function SHOULD be implemented to return a meaningful
  82  * error message for any possible return value of any of the above
  83  * functions.
  84  */
  85 const char *con_errstring(int errno);
  86
  87 #endif