Merge branch 'release-2.140.101'
[feisty_meow.git] / 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