nucleus/library/configuration/ini_configurator.h

   1 #ifndef INI_CONFIGURATOR_CLASS
   2 #define INI_CONFIGURATOR_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : ini_configurator                                                  *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "configurator.h"
  19 #if defined(__UNIX__) || defined(__GNU_WINDOWS__)
  20   #include "ini_parser.h"
  21   #include <basis/utf_conversion.h>
  22 #endif
  23
  24 #include <basis/contracts.h>
  25 #include <filesystem/byte_filer.h>
  26 #include <filesystem/filename.h>
  27
  28 namespace configuration {
  29
  30 //! Supports a configurator-based interface on text initialization files.
  31
  32 class ini_configurator : public configurator
  33 {
  34 public:
  35   //! chooses where the ini file is located if no path to it is provided.
  36   /*! the ini file being manipulated will be stored in either the same
  37   directory as the program being executed (APPLICATION_DIRECTORY) or in the
  38   directory where the operating system resides (OS_DIRECTORY).  however, the
  39   OS_DIRECTORY choice only really makes sense on windows.  if the flag is
  40   instead ALL_USERS_DIRECTORY, then the directory pointed at by the
  41   $ALLUSERSPROFILE variable will be used on windows; otherwise, the default
  42   is the same as for APPLICATION_DIRECTORY. */
  43   enum file_location_default {
  44     APPLICATION_DIRECTORY,  //!< config files live with application.
  45     OS_DIRECTORY,  //!< config files live in operating system directory.
  46     ALL_USERS_DIRECTORY  //!< config files live in the "all users" account.
  47   };
  48
  49   ini_configurator(const basis::astring &ini_filename,
  50           treatment_of_defaults behavior = RETURN_ONLY,
  51           file_location_default where = ALL_USERS_DIRECTORY);
  52     //!< creates an ini_configurator that stores entries into "ini_filename".
  53     /*!< the ini config will have the "behavior" specified for how to handle
  54     missing items.  "where" dictates the file's location if no path is
  55     specified as part of the "ini_filename". */
  56
  57   virtual ~ini_configurator();
  58
  59   DEFINE_CLASS_NAME("ini_configurator");
  60
  61   void refresh();
  62     //!< useful mainly on unix/linux, where the file is parsed and held in memory.
  63
  64 //hmmm: where are:
  65 //  save_to_file()
  66 //  is_modified()
  67 //?
  68
  69   basis::astring name() const;
  70     //!< observes the name of the file used for ini entries.
  71   void name(const basis::astring &name);
  72     //!< modifies the name of the file used for ini entries.
  73
  74   virtual bool get(const basis::astring &section, const basis::astring &entry,
  75           basis::astring &found);
  76     //!< implements the configurator retrieval function.
  77     /*!< this returns true if the entry was present and stores it in
  78     "found". */
  79
  80   virtual void sections(structures::string_array &list);
  81     //!< retrieves the section names into "list".
  82
  83   virtual bool section_exists(const basis::astring &section);
  84     //!< returns true if the "section" was found in the file.
  85     /*!< NOTE: for an INI file, this is quite a heavy-weight call. */
  86
  87   virtual bool put(const basis::astring &section, const basis::astring &entry,
  88           const basis::astring &to_store);
  89     //!< implements the configurator storage function.
  90
  91   virtual bool delete_section(const basis::astring &section);
  92     //!< removes the entire "section" specified.
  93
  94   virtual bool delete_entry(const basis::astring &section, const basis::astring &entry);
  95     //!< removes the entry specified by the "section" and "entry" name.
  96
  97   virtual bool get_section(const basis::astring &section, structures::string_table &info);
  98     //!< reads the entire "section" into a table called "info".
  99     /*!< on win95, this will fail if the section's data exceeds 32K. */
 100
 101   virtual bool put_section(const basis::astring &section, const structures::string_table &info);
 102     //!< writes a table called "info" into the "section" in the INI file.
 103     /*!< any existing data for that section is wiped out.  on win95, this will
 104     fail if the section's data exceeds 32K. */
 105
 106   // dictates whether the stored entries will have spaces between '='
 107   // and the key name and value.  only applicable on linux.
 108   bool add_spaces() const { return _add_spaces; }
 109   void add_spaces(bool add_them) { _add_spaces = add_them; }
 110
 111 private:
 112   filesystem::filename *_ini_name;  //!< the file we're manipulating.
 113 #if defined(__UNIX__) || defined(__GNU_WINDOWS__)
 114   ini_parser *_parser;  //!< used for real storage and parsing.
 115 #endif
 116   file_location_default _where;  //!< where to find and store the file.
 117   bool _add_spaces;  //!< tracks whether we're adding spaces around equals.
 118
 119 #ifdef _MSC_VER
 120   bool put_profile_string(const basis::astring &section, const basis::astring &entry,
 121           const basis::astring &to_store);
 122     //!< encapsulates windows' ini storage method.
 123   void get_profile_string(const basis::astring &section, const basis::astring &entry,
 124           const basis::astring &default_value, basis::flexichar *return_buffer,
 125           int buffer_size);
 126     //!< encapsulates windows' ini retrieval method.
 127 #else
 128   void read_ini_file();
 129     //!< reads the INI file's contents into memory.
 130   void write_ini_file();
 131     //!< store the current contents into the INI file.
 132 #endif
 133
 134   // not to be called.
 135   ini_configurator(const ini_configurator &);
 136   ini_configurator &operator =(const ini_configurator &);
 137
 138   static const basis::astring &ini_str_fake_default();
 139 };
 140
 141 } //namespace.
 142
 143 #endif
 144