nucleus/library/configuration/system_values.h

   1 #ifndef SYSTEM_VALUES_CLASS
   2 #define SYSTEM_VALUES_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : system_values                                                     *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2004-$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 <basis/astring.h>
  19 #include <basis/contracts.h>
  20 //#include <structures/static_memory_gremlin.h>
  21
  22 namespace configuration {
  23
  24 // forward.
  25 class system_values_lookup_list;
  26
  27 //! This class provides a way to look up generated values used in the code base.
  28 /*!
  29   The type of value here includes outcomes, events and filters so far.  These
  30   items are reported in the build manifest that is included with every release
  31   of the compiled software.  The system_values class provides a lookup
  32   interface to the extensible system of unique identifiers which is mapped by
  33   the manifest file.  The manifest file is processed like an initialization
  34   file to retrieve the descriptions and names of symbols when given their
  35   numerical identifiers.
  36 */
  37
  38 class system_values : public virtual basis::root_object
  39 {
  40 public:
  41   system_values(const basis::astring &section_tag);
  42     //!< provides a lookup on values found in the section named "section_tag".
  43     /*!< the "section_tag" indicates what kind of asset is being looked up in
  44     the manifest.  it is always assumed that the manifest file is the main
  45     one defined here in DEFAULT_MANIFEST.  it must be a file created by
  46     the value_tagger during the indexing of all value assets defined in the
  47     build.
  48     the valid values for the section names so far are "DEFINE_ OUTCOME",
  49     "DEFINE_ FILTER" and "DEFINE_ EVENT" (with no spaces), but it is better
  50     to use the defined "VALUES" methods below (such as OUTCOME_VALUES()).
  51     outcomes are used by functions to describe how the operation completed.
  52     filters are used to enable different types of logging.  events are sent
  53     between information source and sink to indicate the occurrence of an
  54     activity. */
  55
  56   virtual ~system_values();
  57
  58   DEFINE_CLASS_NAME("system_values");
  59
  60   // these provide symbolic versions of the section tag used in the
  61   // constructor.  these are preferable to using the string constants
  62   // directly.
  63   static const char *OUTCOME_VALUES();
  64     //!< values that define the outcomes of operations.
  65   static const char *FILTER_VALUES();
  66     //!< values that define filters used in logging.
  67   static const char *EVENT_VALUES();
  68     //!< values that define event objects used in the program.
  69
  70   static const char *DEFAULT_MANIFEST;
  71     //!< the default manifest file.
  72     /*!< it is expected to live in the folder where the applications are. */
  73
  74   bool use_other_manifest(const basis::astring &manifest_file);
  75     //!< supports using a different manifest file than the default.
  76     /*!< the values will now come from the "manifest_file" instead of the
  77     default manifest name shipped with the software release. */
  78
  79   virtual basis::astring text_form() const;
  80     //!< shows all items in the table.
  81
  82   bool lookup(int value, basis::astring &symbolic_name, basis::astring &description,
  83           basis::astring &file_location);
  84     //!< locates a "value" and finds its name, description and location.
  85     /*!< this looks up one of the enumerated values defined for our type of
  86     value.  true is returned if the value is meaningful.  the "symbolic_name"
  87     is set to the item's name as used inside the source code (i.e., its enum
  88     member's name), the "description" is set to the full textual description
  89     of what that value means, and the "file_location" is set to the name of
  90     the source file that defines the value. */
  91
  92   bool lookup(const basis::astring &symbolic_name, int &value, basis::astring &description,
  93           basis::astring &file_location);
  94     //!< similar to the above lookup, but seeks on the "symbolic_name".
  95     /*!< this lookup tries to associate from the textual name of the value
  96     in order to find the integer actual "value" of it.  the textual
  97     "description" and "file_location" for that item are also included. */
  98
  99   int elements() const;
 100     //!< returns how many items are listed for the types of values specified.
 101
 102   bool get(int index, basis::astring &symbolic_name, int &value,
 103            basis::astring &description, basis::astring &file_location);
 104     //!< accesses the "index"th item in the list.
 105
 106 private:
 107   basis::astring *_tag;  //!< the name of our section.
 108   system_values_lookup_list *_list;  //!< the values and text that we found.
 109   basis::astring *_file;  //!< the manifest filename.
 110
 111   bool open_values();  //!< retrieves the information from the file.
 112 };
 113
 114 } //namespace.
 115
 116 #endif
 117