mdw@git.distorted.org.uk Git - ssr/blob - StraySrc/Libraries/Steel/h/prefs

   1 /*
   2  * prefs
   3  *
   4  * Preferences loading and saving
   5  *
   6  * © 1993-1998 Straylight
   7  */
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  13  * Steel is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2, or (at your option)
  16  * any later version.
  17  *
  18  * Steel is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with Steel.  If not, write to the Free Software Foundation,
  25  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26  */
  27
  28 #ifndef __prefs_h
  29 #define __prefs_h
  30
  31 #ifndef __stdio_h
  32   #include <stdio.h>
  33 #endif
  34
  35 /*-----------------------------------------------------------------------
  36
  37   Maybe a few words of description may not go amiss...
  38
  39   This segment manages a preferences file <Appl$Dir>.Choices as far as
  40   loading and saving is concerned.  There were two possibilities for
  41   the format of the file: either you could store the preferences in a
  42   structure type, and just fread and fwrite it (in which case this
  43   wouldn't be here, 'cos doing that is really simple) or as text, in
  44   which case reading and writing can be difficult.  I have chosen the
  45   latter for its versatility, and perhaps even more importantly the fact
  46   that accessing individual options by name will give great scope for
  47   backwards compatibility.
  48
  49   The file is read as lines separated by line feeds.  Each line can be
  50   either blank (self-explanatory), a comment (begins with a ';') or
  51   an assignment.  An assignment has the following syntax:
  52
  53     <assignment> ::= <tag> [=] <value>
  54
  55   <tag> and <value> can be any valid ASCII strings.
  56
  57   The method envisaged for the use of this system is as follows:
  58
  59    * A structure type (prefs_prefstr) is defined here in this header.
  60      The application should define a bunch of static variables (the
  61      lifetime is important, not the scope) to store the actual choices.
  62
  63    * Then the application defines a static array of prefs_prefstrs, and
  64      fills it with entries as follows:
  65
  66        tag == pointer to a tag name to match
  67        read == a procedure to interpret a line matched with the tag
  68        write == a procedure to write out all lines with the tag
  69        handle == a pointer type passed to both procedures
  70
  71   The procedures must return 0 for success, or a pointer to an error
  72   message.  The standard employed by the routines in this segment is
  73   that handle points to the variable to be read/written.  Thus, a
  74   concept of variable types can be built up over time.  I have included
  75   processors for the three main data types likely to appear: boolean,
  76   integer and string.  The layout of these has been to make the Choices
  77   file as human-intelligible as possible.
  78
  79   Tags in the structure beginning with ';' or '\n' are not sent to read/
  80   write procedures, but instead are written directly to the file, and
  81   ignored when reading.  Thus, you can insert comments (like copyright
  82   messages) and spacing to give the file a well-designed look.
  83
  84                                           Straylight
  85
  86 -----------------------------------------------------------------------*/
  87
  88 typedef char *(*prefs_readproc)(char *tag,char *args,void *handle);
  89 typedef char *(*prefs_writeproc)(char *tag,FILE *fp,void *handle);
  90
  91 typedef struct
  92 {
  93   char *tag;
  94   prefs_readproc read;
  95   prefs_writeproc write;
  96   void *handle;
  97 }
  98 prefs_prefstr;
  99
 100 /*
 101  * char *prefs_readBoolean(char *tag,char *args,void *handle)
 102  *
 103  * Use
 104  *  Reads a Boolean variable (i.e. one that can be either TRUE or FALSE).
 105  */
 106
 107 char *prefs_readBoolean(char *tag,char *args,void *handle);
 108
 109 /*
 110  * char *prefs_writeBoolean(char *tag,FILE *fp,void *handle)
 111  *
 112  * Use
 113  *  Writes a Boolean variable to the preferences file.
 114  */
 115
 116 char *prefs_writeBoolean(char *tag,FILE *fp,void *handle);
 117
 118 /*
 119  * char *prefs_readNumeric(char *tag,char *args,void *handle)
 120  *
 121  * Use
 122  *  Reads a signed integer from the preferences file.
 123  */
 124
 125 char *prefs_readNumeric(char *tag,char *args,void *handle);
 126
 127 /*
 128  * char *prefs_writeNumeric(char *tag,FILE *fp,void *handle)
 129  *
 130  * Use
 131  *  Writes a signed integer to the preferences file.
 132  */
 133
 134 char *prefs_writeNumeric(char *tag,FILE *fp,void *handle);
 135
 136 /*
 137  * char *prefs_readString(char *tag,char *args,void *handle)
 138  *
 139  * Use
 140  *  Reads a string from the preferences file.  It is assumed that the buffer
 141  *  pointed to by handle is big enough.
 142  */
 143
 144 char *prefs_readString(char *tag,char *args,void *handle);
 145
 146 /*
 147  * char *prefs_writeString(char *tag,FILE *fp,void *handle)
 148  *
 149  * Use
 150  *  Writes a signed integer to the preferences file.
 151  */
 152
 153 char *prefs_writeString(char *tag,FILE *fp,void *handle);
 154
 155 /*
 156  * void prefs_preferences(prefs_prefstr *p)
 157  *
 158  * Use
 159  *  Sets up the prefs system to use the preferences definition specified.
 160  *  'p' should be a pointer to an array of prefs_prefstrs, terminated by an
 161  *  entry with a null 'tag'.  The preferences file created will be called
 162  *  'Choices' in the current application's directory (<App$Dir>.Choices).
 163  *
 164  * Parameters
 165  *  prefs_prefstr *p == pointer to an array of preferences definitions
 166  */
 167
 168 void prefs_preferences(prefs_prefstr *p);
 169
 170 /*
 171  * void prefs_read(void)
 172  *
 173  * Use
 174  *  Reads preferences from the preferences file.
 175  */
 176
 177 void prefs_read(void);
 178
 179 /*
 180  * void prefs_write(void)
 181  *
 182  * Use
 183  *  Writes preferences out to disk.
 184  */
 185
 186 void prefs_write(void);
 187
 188 #endif