wow. that was easy: git mv core nucleus

[feisty_meow.git] / nucleus / library / configuration / section_manager.h

diff --git a/nucleus/library/configuration/section_manager.h b/nucleus/library/configuration/section_manager.h
new file mode 100644 (file)
index 0000000..dea180c
--- /dev/null
+++ b/nucleus/library/configuration/section_manager.h
@@ -0,0 +1,111 @@
+#ifndef SECTION_MANAGER_CLASS
+#define SECTION_MANAGER_CLASS
+
+/*****************************************************************************\
+*                                                                             *
+*  Name   : section_manager                                                   *
+*  Author : Chris Koeritz                                                     *
+*                                                                             *
+*******************************************************************************
+* Copyright (c) 2000-$now By Author.  This program 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 of   *
+* the License or (at your option) any later version.  This is online at:      *
+*     http://www.fsf.org/copyleft/gpl.html                                    *
+* Please send any updates to: fred@gruntose.com                               *
+\*****************************************************************************/
+
+#include "configurator.h"
+
+#include <structures/string_table.h>
+
+namespace configuration {
+
+//! Tracks a collection of related configurations in a configurator.
+/*!
+  If there is a set of items that need to be stored in a configurator, where
+  each item has its own configuration section, then this object can help out.
+  It manages a collection of uniquely named sections in a configurator object
+  and provides a table of contents (TOC) feature for the names of the sections.
+  Each item lives in its own distinct section but the whole set can be
+  operated on as one entity.
+*/
+
+class section_manager : public virtual basis::nameable
+{
+public:
+  section_manager(configurator &config, const basis::astring &toc_title,
+          const basis::astring &header_prefix);
+    //!< creates a section_manager that uses the "config" for storage.
+    /*!< the "toc_title" is the name of the section to be used for storing the
+    table of contents for the managed configuration items.  the "header_prefix"
+    will be prepended to the names of each section to facilitate locating them.
+    for example, if the "toc_title" is "client channels" and the "header_prefix"
+    is "CliChan__", then the resulting configuration might look similar to the
+    following: @code
+      [client channels]
+      joe
+      ted
+      [CliChan__joe]
+      port=58
+      [CliChan__ted]
+      address=13.8.92.4
+      auth=primary
+    @endcode */
+
+  ~section_manager();
+
+  DEFINE_CLASS_NAME("section_manager");
+
+  bool section_exists(const basis::astring &section_name);
+    //!< returns true if the section called "section_name" exists in the config.
+
+  bool get_section_names(structures::string_array &sections);
+    //!< loads the "sections" array with all section names.
+    /*!< this comes from our table of contents.  true is returned if there
+    were any names to load. */
+
+  bool add_section(const basis::astring &section_name, const structures::string_table &to_add);
+    //!< stores a new section for "section_name" using the table "to_add".
+    /*!< this will fail if the section already exists. */
+
+  bool replace_section(const basis::astring &section, const structures::string_table &replacement);
+    //!< replaces the contents of "section" with the "replacement" table.
+    /*!< this will fail if the section does not already exist. */
+
+  bool zap_section(const basis::astring &section_name);
+    //!< removes the data for "section_name" from both the config and TOC.
+    /*!< this will fail if the section is not present. */
+
+  bool find_section(const basis::astring &section_name, structures::string_table &found);
+    //!< loads the data from "section_name" into the table "found".
+    /*!< this fails if the section doesn't exist or if the section's contents
+    couldn't be detokenized into a table of name/value pairs. */
+
+  configurator &config() { return _config; }
+    //!< allows access to the configurator we operate on.
+    /*!< getting single items from the config will be signficantly faster
+    using it directly; the make_section_heading() method can be used to locate
+    the proper section. */
+
+  bool get_toc(structures::string_table &toc);
+    //!< reads the table of contents into "toc".
+
+  basis::astring make_section_heading(const basis::astring &section);
+    //!< provides the appropriate heading string for the "section" name.
+    /*!< this can be used to find entries using the config(). */
+
+private:
+  configurator &_config;  //!< the configuration object we interact with.
+  basis::astring *_toc_title;  //!< the table of contents' section name.
+  basis::astring *_section_prefix;  //!< prefix attached to the name of the section.
+
+  section_manager(const section_manager &);  //!< currently forbidden.
+  section_manager &operator =(const section_manager &);
+    //!< currently forbidden.
+};
+
+} //namespace.
+
+#endif
+