nucleus/library/configuration/section_manager.h

   1 #ifndef SECTION_MANAGER_CLASS
   2 #define SECTION_MANAGER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : section_manager                                                   *
   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
  20 #include <structures/string_table.h>
  21
  22 namespace configuration {
  23
  24 //! Tracks a collection of related configurations in a configurator.
  25 /*!
  26   If there is a set of items that need to be stored in a configurator, where
  27   each item has its own configuration section, then this object can help out.
  28   It manages a collection of uniquely named sections in a configurator object
  29   and provides a table of contents (TOC) feature for the names of the sections.
  30   Each item lives in its own distinct section but the whole set can be
  31   operated on as one entity.
  32 */
  33
  34 class section_manager : public virtual basis::nameable
  35 {
  36 public:
  37   section_manager(configurator &config, const basis::astring &toc_title,
  38           const basis::astring &header_prefix);
  39     //!< creates a section_manager that uses the "config" for storage.
  40     /*!< the "toc_title" is the name of the section to be used for storing the
  41     table of contents for the managed configuration items.  the "header_prefix"
  42     will be prepended to the names of each section to facilitate locating them.
  43     for example, if the "toc_title" is "client channels" and the "header_prefix"
  44     is "CliChan__", then the resulting configuration might look similar to the
  45     following: @code
  46       [client channels]
  47       joe
  48       ted
  49       [CliChan__joe]
  50       port=58
  51       [CliChan__ted]
  52       address=13.8.92.4
  53       auth=primary
  54     @endcode */
  55
  56   ~section_manager();
  57
  58   DEFINE_CLASS_NAME("section_manager");
  59
  60   bool section_exists(const basis::astring &section_name);
  61     //!< returns true if the section called "section_name" exists in the config.
  62
  63   bool get_section_names(structures::string_array &sections);
  64     //!< loads the "sections" array with all section names.
  65     /*!< this comes from our table of contents.  true is returned if there
  66     were any names to load. */
  67
  68   bool add_section(const basis::astring &section_name, const structures::string_table &to_add);
  69     //!< stores a new section for "section_name" using the table "to_add".
  70     /*!< this will fail if the section already exists. */
  71
  72   bool replace_section(const basis::astring &section, const structures::string_table &replacement);
  73     //!< replaces the contents of "section" with the "replacement" table.
  74     /*!< this will fail if the section does not already exist. */
  75
  76   bool zap_section(const basis::astring &section_name);
  77     //!< removes the data for "section_name" from both the config and TOC.
  78     /*!< this will fail if the section is not present. */
  79
  80   bool find_section(const basis::astring &section_name, structures::string_table &found);
  81     //!< loads the data from "section_name" into the table "found".
  82     /*!< this fails if the section doesn't exist or if the section's contents
  83     couldn't be detokenized into a table of name/value pairs. */
  84
  85   configurator &config() { return _config; }
  86     //!< allows access to the configurator we operate on.
  87     /*!< getting single items from the config will be signficantly faster
  88     using it directly; the make_section_heading() method can be used to locate
  89     the proper section. */
  90
  91   bool get_toc(structures::string_table &toc);
  92     //!< reads the table of contents into "toc".
  93
  94   basis::astring make_section_heading(const basis::astring &section);
  95     //!< provides the appropriate heading string for the "section" name.
  96     /*!< this can be used to find entries using the config(). */
  97
  98 private:
  99   configurator &_config;  //!< the configuration object we interact with.
 100   basis::astring *_toc_title;  //!< the table of contents' section name.
 101   basis::astring *_section_prefix;  //!< prefix attached to the name of the section.
 102
 103   section_manager(const section_manager &);  //!< currently forbidden.
 104   section_manager &operator =(const section_manager &);
 105     //!< currently forbidden.
 106 };
 107
 108 } //namespace.
 109
 110 #endif
 111