/*!
  @mainpage The Vars Library

  <center>Glenn Hutchings (zondo42@googlemail.com)</center>

  The Vars library is a general-purpose library of C functions which allows
  you to create and manipulate @ref types "objects".  There are many
  different builtin object types:

  - @ref scalar are the basic unit of data, and contain a single number,
    string or pointer.
  - @ref list, @ref hash, @ref array, @ref graph and @ref queue act as
    containers for scalars.
  - @ref func and @ref array are suitable for performing interpolation and
    extrapolation.
  - @ref graph can be used to model a network of connections, and find
    shortest paths.
  - @ref queue are useful in event-based simulation systems.
  - @ref buffer are available for storing variable-length strings.
  - @ref vector and @ref matrix store floating-point values in the way you
    would expect.
  - @ref image are available for manipulation of colour and grayscale
    images in many different formats.
  - @ref regex can be used to perform string pattern matching.
  - @ref parser are useful for evaluating mathematical expressions which
    are defined at run time.
  - @ref database can be used to store and manipulate data records of
    various types.
  .

  Object and their types have several properties:

  - They can have @ref persist "persistence" (i.e., their state can be saved
    to or restored from files).
  - Container objects can be @ref iterate "iterated" over to inspect their
    contents.
  - The builtin types can be @ref extend "extended" by defining your own
    types.
  .

  The Vars library also has functions for many other purposes: @ref options
  "option parsing", accessing the @ref system "system", @ref debug
  "debugging" and @ref util "more".  You can find how to use the library in
  your own programs @ref usage "here".

  The Vars library is distributed under the @ref license
  "GNU Lesser Public License".
*/

/*!
  @page usage Using the library

  To use the library functions in your own programs, you must include the
  header file @c vars.h in the source, and then compile and link the
  program using the Vars headers and library.  As a convenience, there's a
  configuration script called @c vars-config which prints the required
  compiler/linker options; you can use it like this:

  @verbatim
  cc `vars-config --cflags` -c -o prog.o prog.c
  cc -o prog prog.o `vars-config --libs`
  @endverbatim
*/

/*!
  @page problems Design problems

  Some things in the Vars library turned out to be a bad idea;
  unfortunately, now it's very hard to change them:

  - Things were written without thread-safety in mind.  As a result, unless
    a function says it's thread-safe, you must assume it's not.
  - The use of a single letter in function names to indicate the object
    type was a mistake.  I'm sure there's only a finite supply...
  - The name 'Vars' is short for 'Variables'.  In retrospect, this was a
    rubbish name.
  .

  The old method of iteration over objects, via the @c v*_foreach() macros,
  had serious problems:

  -# Iteration was done by keeping an internal counter inside the object,
     which meant that an object couldn't be iterated over simultaneously by
     two different functions; worse, there was no way to guard against it.
  -# If the iteration loop was exited prematurely, a @c v*_break() function
     had to be called to reset the internal counter.  This led to subtle
     errors when the call was missed out.
  .

  The @ref iterate "new method" of object iteration removes both these
  problems, and you shouldn't use the old method in new code.  However, due
  to the amount of legacy code out there, the old buggy method is still
  supported for now.
*/

/*!
  @page license License
  @verbinclude COPYING
*/

/*!
  @page changes Change history
  @verbinclude NEWS
*/

/*!
  @defgroup types Objects

  These are the builtin object types.
*/

/*!
  @defgroup methods Methods

  These are the standard object methods.
*/

/*
 * Local Variables:
 * mode: c
 * End:
 */