/*
 * prefs
 *
 * Preferences loading and saving
 *
 * © 1993-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __prefs_h
#define __prefs_h

#ifndef __stdio_h
  #include <stdio.h>
#endif

/*-----------------------------------------------------------------------

  Maybe a few words of description may not go amiss...

  This segment manages a preferences file <Appl$Dir>.Choices as far as
  loading and saving is concerned.  There were two possibilities for
  the format of the file: either you could store the preferences in a
  structure type, and just fread and fwrite it (in which case this
  wouldn't be here, 'cos doing that is really simple) or as text, in
  which case reading and writing can be difficult.  I have chosen the
  latter for its versatility, and perhaps even more importantly the fact
  that accessing individual options by name will give great scope for
  backwards compatibility.

  The file is read as lines separated by line feeds.  Each line can be
  either blank (self-explanatory), a comment (begins with a ';') or
  an assignment.  An assignment has the following syntax:

    <assignment> ::= <tag> [=] <value>

  <tag> and <value> can be any valid ASCII strings.

  The method envisaged for the use of this system is as follows:

   * A structure type (prefs_prefstr) is defined here in this header.
     The application should define a bunch of static variables (the
     lifetime is important, not the scope) to store the actual choices.

   * Then the application defines a static array of prefs_prefstrs, and
     fills it with entries as follows:

       tag == pointer to a tag name to match
       read == a procedure to interpret a line matched with the tag
       write == a procedure to write out all lines with the tag
       handle == a pointer type passed to both procedures

  The procedures must return 0 for success, or a pointer to an error
  message.  The standard employed by the routines in this segment is
  that handle points to the variable to be read/written.  Thus, a
  concept of variable types can be built up over time.  I have included
  processors for the three main data types likely to appear: boolean,
  integer and string.  The layout of these has been to make the Choices
  file as human-intelligible as possible.

  Tags in the structure beginning with ';' or '\n' are not sent to read/
  write procedures, but instead are written directly to the file, and
  ignored when reading.  Thus, you can insert comments (like copyright
  messages) and spacing to give the file a well-designed look.

                                          Straylight

-----------------------------------------------------------------------*/

typedef char *(*prefs_readproc)(char *tag,char *args,void *handle);
typedef char *(*prefs_writeproc)(char *tag,FILE *fp,void *handle);

typedef struct
{
  char *tag;
  prefs_readproc read;
  prefs_writeproc write;
  void *handle;
}
prefs_prefstr;

/*
 * char *prefs_readBoolean(char *tag,char *args,void *handle)
 *
 * Use
 *  Reads a Boolean variable (i.e. one that can be either TRUE or FALSE).
 */

char *prefs_readBoolean(char *tag,char *args,void *handle);

/*
 * char *prefs_writeBoolean(char *tag,FILE *fp,void *handle)
 *
 * Use
 *  Writes a Boolean variable to the preferences file.
 */

char *prefs_writeBoolean(char *tag,FILE *fp,void *handle);

/*
 * char *prefs_readNumeric(char *tag,char *args,void *handle)
 *
 * Use
 *  Reads a signed integer from the preferences file.
 */

char *prefs_readNumeric(char *tag,char *args,void *handle);

/*
 * char *prefs_writeNumeric(char *tag,FILE *fp,void *handle)
 *
 * Use
 *  Writes a signed integer to the preferences file.
 */

char *prefs_writeNumeric(char *tag,FILE *fp,void *handle);

/*
 * char *prefs_readString(char *tag,char *args,void *handle)
 *
 * Use
 *  Reads a string from the preferences file.  It is assumed that the buffer
 *  pointed to by handle is big enough.
 */

char *prefs_readString(char *tag,char *args,void *handle);

/*
 * char *prefs_writeString(char *tag,FILE *fp,void *handle)
 *
 * Use
 *  Writes a signed integer to the preferences file.
 */

char *prefs_writeString(char *tag,FILE *fp,void *handle);

/*
 * void prefs_preferences(prefs_prefstr *p)
 *
 * Use
 *  Sets up the prefs system to use the preferences definition specified.
 *  'p' should be a pointer to an array of prefs_prefstrs, terminated by an
 *  entry with a null 'tag'.  The preferences file created will be called
 *  'Choices' in the current application's directory (<App$Dir>.Choices).
 *
 * Parameters
 *  prefs_prefstr *p == pointer to an array of preferences definitions
 */

void prefs_preferences(prefs_prefstr *p);

/*
 * void prefs_read(void)
 *
 * Use
 *  Reads preferences from the preferences file.
 */

void prefs_read(void);

/*
 * void prefs_write(void)
 *
 * Use
 *  Writes preferences out to disk.
 */

void prefs_write(void);

#endif