您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

configuration.hpp 44KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714
  1. // configuration.hpp
  2. //
  3. // Copyright (C) 2004-2020 MicroNeil Research Corporation.
  4. //
  5. // This software is released under the MIT license. See LICENSE.TXT.
  6. // What about this =============================================================
  7. // The configuration module provides a platform for reading configuration files
  8. // (or string data) containing well-formed xml and mapping that data to program
  9. // variables.
  10. //
  11. // The idea is to provide the ability for an object or application to provide
  12. // a modular "configuration" object that models a hierarchical collection of
  13. // "settings" that can be represented easily in code and in xml.
  14. //
  15. // The following is an example model of a configuration in code and that same
  16. // configuration fully populated in xml.
  17. //
  18. // The code might look like this...
  19. //
  20. // int IntValue, DefaultInt = 3;
  21. // double DblValue, DefaultDbl = 3.14159;
  22. // bool BooleanValue, DefaultBool = false;
  23. // string StringValue, DefaultString = "NoStringHere";
  24. //
  25. // SpecialConfigurator : public ConfigurationHandler { // Create a special handler to build a list
  26. // ...
  27. // public:
  28. //
  29. // ConfigurationHandler& Startup(ConfigurationElement& E) { // This function returns a handy handler to
  30. // return MyStartupConfigurationHandler; // (re) initialize this handler ;-)
  31. // }
  32. //
  33. // void Operator()() { // Each time the configurator is called
  34. // ...
  35. // }
  36. //
  37. // int Attribute1; // these items are interpreted and added
  38. // double Attribute2; // to the list. A ConfigurationHandler COULD
  39. // string Attribute3; // do something entirely different though ;-)
  40. // string Contents;
  41. // ...
  42. // } Special;
  43. //
  44. // ConfigurationElement SampleConfig("SampleConfiguration"); // Define a sample config (doc element)
  45. // SampleConfig // Populate the SampleConfig
  46. // .atStartCall(Special.Startup())
  47. // .Element("Integer", IntValue, DefaultInt).End() // Link an element to an int w/ default.
  48. // .Element("Double", DblValue, DefaultDbl).End("Double") // Link an element to a dbl w/ default.
  49. // .Element("String", StringValue, DefaultString).End("String") // Link an element to a string w/ default.
  50. // .Element("ComplexElements") // Create a sub element.
  51. // .Element("Complex1") // Sub element Complex1 has attributes.
  52. // .Attribute("IntAtt", IntValue, DefaultInt) // Complex1 has an integer attribute.
  53. // .Attribute("DblAtt", DblValue, DefaultDbl) // Complex1 has a dbl attribute.
  54. // .Element("IntAtt", IntValue).End() // IntAtt can also be set by a sub element.
  55. // .Element("DblAtt", DblValue).End() // DblAtt can also be set by a sub element.
  56. // .End() // That's it for Complex1.
  57. // .Element("Complex2") // Create the Complex2 sub element.
  58. // .Attribute("C2I", IntValue, DefaultInt) // C2I attribute.
  59. // .Attribute("C2D", DblValue) // C2D attribute - no default.
  60. // .Attribute("C2S", StringValue, DefultString) // C2S attribute - string w/ default.
  61. // .End("Complex2") // End of element throws if doesn't match.
  62. // .Element("Complex3", Special.Contents) // Element 3 using a special configurator.
  63. // .Attribute("A1", Special.Attribute1) // Set A1 and A2 and A3 and when the
  64. // .Attribute("A2", Special.Attribute2) // element has been completed, Special()
  65. // .Attribute("A3", Special.Attribute3) // will be called to record the entries.
  66. // .atEndCall(Special) // Here's where we register the handler.
  67. // .End() // Closing Complex3 to be ice.
  68. // .End() // Closing ComplexElements to be nice.
  69. // .End(); // Closing SampleConfiguration to be nice.
  70. //
  71. // The XML might look like this...
  72. //
  73. // <SampleConfiguration>
  74. // <Integer>10</Integer>
  75. // <Double>2.4</Double>
  76. // <String>This is a sample string</String>
  77. // <ComplexElements>
  78. // <Complex1 IntAtt="4" DblAtt="2.1324">
  79. // <IntAtt>24</IntAtt> <!-- changed IntAtt -->
  80. // </Complex1>
  81. // <Complex2 C2I='3' C2D='5.14' C2S='Some "string" we like' />
  82. // <Complex3> stuff in here </Complex3>
  83. // <Complex3> Another instance </Complex3>
  84. // <Complex3> Each one gets passed to Special() on activation </Complex3>
  85. // <Complex3> This way, Special() can build a list or some other </Complex3>
  86. // <Complex3> interesting thing with all of these. </Complex3>
  87. // <ComplexElements>
  88. // </SampleConfiguration>
  89. //
  90. // Include This Header Once Only ===============================================
  91. #pragma once
  92. #include <string>
  93. #include <vector>
  94. #include <sstream>
  95. #include <fstream>
  96. #include <cstring>
  97. #include <cstdlib>
  98. #include <list>
  99. namespace codedweller {
  100. class ConfigurationElement; // Elements exist
  101. class ConfigurationAttribute; // Attributes exist
  102. class ConfigurationData; // Data exists
  103. class ConfigurationTranslator; // Translators exist
  104. class ConfigurationMnemonic; // Mnemonics exist
  105. class Configurator; // Configurators exist
  106. //// Configuration Element /////////////////////////////////////////////////////
  107. //
  108. // Elements make up the core of a configuration. That is, a configuration is a
  109. // tree of elements. Elements translate directly to well formed xml elements in
  110. // a configuration file or string.
  111. class ConfigurationElement {
  112. private:
  113. std::string myName; // Elements have a name.
  114. // External important things I remember but don't touch...
  115. ConfigurationElement* myParent; // They may have a parrent.
  116. std::list<Configurator*> myStartConfigurators; // Call these when we start Interpret()
  117. std::list<Configurator*> myEndConfigurators; // Call these when we finish Interpret()
  118. // Internal / subordinate things I own and kill...
  119. std::list<ConfigurationAttribute*> myAttributes; // They may have a list of attributes.
  120. std::list<ConfigurationElement*> myElements; // They may have a list of sub-elements.
  121. std::list<ConfigurationMnemonic*> myMnemonics; // They may have a list of mnemonics.
  122. std::list<ConfigurationTranslator*> myTranslators; // They may have a list of translators.
  123. // During Interpret() operations we keep track of where we are seen...
  124. int myLine; // Last line number I was seen on.
  125. int myIndex; // Last char position I was seen on.
  126. int myLength; // Last segment length.
  127. bool myCleanFlag; // Keep track of initialization.
  128. bool myInitOnInterpretFlag; // Initialize() at each Interpret()?
  129. void runStartConfigurators(ConfigurationData& D); // Does what it says ;-)
  130. void runEndConfigurators(ConfigurationData& D); // Does what it says ;-)
  131. public:
  132. ConfigurationElement(const char* Name); // Must be constructed with a name
  133. ConfigurationElement(const std::string Name); // either c string or c++ string.
  134. ConfigurationElement(const char* Name, ConfigurationElement& Parent); // Sub-elements are constructed with a
  135. ConfigurationElement(const std::string Name, ConfigurationElement& Parent); // parrent.
  136. // Upon desctruction an element will delete all subordinate objects:
  137. // * All sub element objects.
  138. // * All attribute objects.
  139. // * All mnemonic objects.
  140. // * All translator objects.
  141. // It is important to use new when passing one of these objects to an
  142. // element or attribute to prevent problems with the delete operation.
  143. // NORMALLY these things would be created using factory methods on the
  144. // element and attribute objects themselves - so be careful.
  145. // It will not delete Configurators - they must
  146. // be deleted elsewhere because they may have been
  147. // re-used and this element wouldn't know about it ;-)
  148. ~ConfigurationElement(); // The descrutor clears and deletes all!
  149. // Elements can be probed for some simple, useful things.
  150. std::string Name(); // Get the name of this element.
  151. ConfigurationElement& Parent(); // Get the parent of this element.
  152. ConfigurationElement& Parent(ConfigurationElement& newParent); // Set the parent of this element.
  153. // Note - if there is no parent (an element is the root) then it will
  154. // return a reference to itself when Parent() is called.
  155. int Line(); // Get the last line number.
  156. int Index(); // Get the last data position.
  157. int Length(); // Get the last length.
  158. // Elements can contain either data or sub-elements.
  159. ConfigurationElement& Element(const char* Name); // Add a new sub element by c string name.
  160. ConfigurationElement& Element(const std::string Name); // Add a new sub element by c++ string name.
  161. //// Mapping element factory methods for convenience.
  162. //// Root-Node elements are _usually_ empty and without attributes in xml
  163. //// so we don't make any of that type of convenience constructor here.
  164. // char* versions
  165. ConfigurationElement& Element( // Mapping factory for convenience,
  166. const char* Name, // requires a name, of course,
  167. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  168. ConfigurationElement& Element( // Mapping factory for convenience,
  169. const char* Name, // requires a name, of course,
  170. std::string& x, std::string init = std::string("")); // Map to a string.
  171. ConfigurationElement& Element( // Mapping factory for convenience,
  172. const char* Name, // requires a name, of course,
  173. int& x, int init = 0, int radix = 0); // Map to an int.
  174. ConfigurationElement& Element( // Mapping factory for convenience,
  175. const char* Name, // requires a name, of course,
  176. double& x, double init = 0.0); // Map to a double.
  177. ConfigurationElement& Element( // Mapping factory for convenience,
  178. const char* Name, // requires a name, of course,
  179. bool& x, bool init = false); // Map to a boolean.
  180. // string versions
  181. ConfigurationElement& Element( // Mapping factory for convenience,
  182. const std::string Name, // requires a name, of course,
  183. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  184. ConfigurationElement& Element( // Mapping factory for convenience,
  185. const std::string Name, // requires a name, of course,
  186. std::string& x, std::string init = std::string("")); // Map to a string.
  187. ConfigurationElement& Element( // Mapping factory for convenience,
  188. const std::string Name, // requires a name, of course,
  189. int& x, int init = 0, int radix = 0); // Map to an int.
  190. ConfigurationElement& Element( // Mapping factory for convenience,
  191. const std::string Name, // requires a name, of course,
  192. double& x, double init = 0.0); // Map to a double.
  193. ConfigurationElement& Element( // Mapping factory for convenience,
  194. const std::string Name, // requires a name, of course,
  195. bool& x, bool init = false); // Map to a boolean.
  196. // End methods for heading back up the tree at the end of an element.
  197. class EndNameDoesNotMatch {}; // Throw when End(name) doesn't match.
  198. ConfigurationElement& End(); // Return this element's parent.
  199. ConfigurationElement& End(const char* Name); // Check the name and return the parent
  200. ConfigurationElement& End(const std::string Name); // if the name is correct - or throw!
  201. // Elements can have attributes.
  202. ConfigurationAttribute& Attribute(const char* Name); // Add an attribute using a cstring.
  203. ConfigurationAttribute& Attribute(const std::string Name); // Add an attribute using a c++ string.
  204. //// Mapping Attribute factory methods for convenience.
  205. // char* versions
  206. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  207. const char* Name, // requires a name, of course,
  208. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  209. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  210. const char* Name, // requires a name, of course,
  211. std::string& x, std::string init = std::string("")); // Map to a string.
  212. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  213. const char* Name, // requires a name, of course,
  214. int& x, int init = 0, int radix = 0); // Map to an int.
  215. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  216. const char* Name, // requires a name, of course,
  217. double& x, double init = 0.0); // Map to a double.
  218. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  219. const char* Name, // requires a name, of course,
  220. bool& x, bool init = false); // Map to a boolean.
  221. // string versions
  222. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  223. const std::string Name, // requires a name, of course,
  224. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  225. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  226. const std::string Name, // requires a name, of course,
  227. std::string& x, std::string init = std::string("")); // Map to a string.
  228. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  229. const std::string Name, // requires a name, of course,
  230. int& x, int init = 0, int radix = 0); // Map to an int.
  231. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  232. const std::string Name, // requires a name, of course,
  233. double& x, double init = 0.0); // Map to a double.
  234. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  235. const std::string Name, // requires a name, of course,
  236. bool& x, bool init = false); // Map to a boolean.
  237. // Elements can Initialize() at each Interpret() call.
  238. ConfigurationElement& setInitOnInterpret(); // Set the init on interpret flag.
  239. // Elements can call external functions to aid in special operations
  240. // such as building lists.
  241. ConfigurationElement& atStartCall(Configurator& Functor); // Add an atStart call-back to this element.
  242. ConfigurationElement& atEndCall(Configurator& Functor); // Add an atEnd call-back to this element.
  243. // Extracting data from the element's contents is done with
  244. // translators. A good set of primatives are built in, but the user
  245. // can also make their own. If an Element is mapped to more than
  246. // one then they are all called once the element's contents are
  247. // collected. A translator takes the data provided by the element,
  248. // converts it into the expected type, and sets one or more variables
  249. // to the converted value. Usually - just one variable.
  250. ConfigurationElement& mapTo(ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  251. ConfigurationElement& mapTo(std::string& x, std::string init = std::string("")); // Map to a string.
  252. ConfigurationElement& mapTo(int& x, int init = 0, int radix = 0); // Map to an int.
  253. ConfigurationElement& mapTo(double& x, double init = 0.0); // Map to a double.
  254. ConfigurationElement& mapTo(bool& x, bool init = false); // Map to a boolean.
  255. // An Element's contents may use some special mnemonics to make a
  256. // configuration easier to understand and less error prone. When the
  257. // contents match a mnemnoic then the translation of the mnemonic is
  258. // passed to the Translators instead of the raw contents.
  259. ConfigurationElement& Mnemonic(const char* name, const char* value); // Add a mnemonic using c strings.
  260. ConfigurationElement& Mnemonic(const char* name, const std::string value); // Add a mnemonic using c & c++ strings.
  261. ConfigurationElement& Mnemonic(const std::string name, const char* value); // Add a mnemonic using c++ & c strings.
  262. ConfigurationElement& Mnemonic(const std::string name, const std::string value); // Add a mnemonic using c++ strings.
  263. // The way data gets into an element tree is that it is Interpret()ed
  264. // recursively. The data is loaded into a ConfigurationData object which
  265. // is passed to the top Element. That element interpretes the data, moves
  266. // the interpretation pointers, and passes the data on to it's subordinate
  267. // elements in turn. They do the same recursively. When the last sub -
  268. // element has had it's way with the data, the interpretation process is
  269. // complete. The ConfigurationData object will contain the original data
  270. // and a log of anything that happened during the interpretation process.
  271. //
  272. // Each time an element is asked to Interpret() data, it calls any atStart
  273. // configurators, translates any attributes, then either translates it's
  274. // contents or passes the data to it's children, then calls any atEnd
  275. // configurators.
  276. //
  277. // To ensure that the correct default values are used the Initialize() is
  278. // always called on all internal attributes and elements before any data is
  279. // interpreted. To prevent this from being inefficient, a boolean flag is
  280. // kept in each element to keep track of whether it is clean and if it is
  281. // then the call to Initialize will simply return (skipping subordinate
  282. // elements along the way).
  283. //
  284. // Interpret returns true if this object found itself at the current
  285. // Data.Index and false if not. This helps keep the recursive parsing
  286. // code simpler ;-)
  287. void initialize(); // Reset all translators to defaults.
  288. void notifyDirty(); // Set dirty (if translators change).
  289. bool interpret(ConfigurationData& Data); // (re) Interpret this data.
  290. };
  291. //// Configuration Attribute ///////////////////////////////////////////////////
  292. //
  293. // Attributes translate directly to well formed xml attributes (within the
  294. // start tag of an element).
  295. class ConfigurationAttribute {
  296. private:
  297. std::string myName; // Elements have a name.
  298. ConfigurationElement& myParent; // They may have a parrent.
  299. std::list<ConfigurationMnemonic*> myMnemonics; // They may have a list of mnemonics.
  300. std::list<ConfigurationTranslator*> myTranslators; // They may have a list of translators.
  301. int myLine; // Last line number I was seen on.
  302. int myIndex; // Last char position I was seen on.
  303. int myLength; // Last segment length.
  304. public:
  305. ConfigurationAttribute(const char* Name, ConfigurationElement& Parent); // Sub-elements are constructed with a
  306. ConfigurationAttribute(const std::string Name, ConfigurationElement& Parent); // parrent.
  307. // Attributes delete their Mnemonics and Translators when they go.
  308. // See Elements for similar warnings about objects provided to
  309. // this object... you must use new to be safe, or better yet - stick to
  310. // the built in factory methods ;-)
  311. ~ConfigurationAttribute(); // Crush, Kill, Destroy!
  312. // Attributes can be probed for some simple, useful things.
  313. std::string Name(); // Get the name of this attribute.
  314. ConfigurationElement& Parent(); // Get the parent of this attribute.
  315. int Line(); // Get the last line number.
  316. int Index(); // Get the last data position.
  317. int Length(); // Get the last length.
  318. void notifyDirty(); // Attributes use this when they change.
  319. // For convenience in building configurations, an Attribute offers
  320. // some call-through methods to it's parrent Element. This allows for
  321. // clear, concise .method() coding that mimics an outline of the
  322. // configuration structure.
  323. //// For switching back to the parent element and adding new sub-elements.
  324. ConfigurationElement& Element(const char* Name); // Add a new sub element by c string name.
  325. ConfigurationElement& Element(const std::string Name); // Add a new sub element by c++ string name.
  326. //// Mapping element factory methods for convenience.
  327. //// Root-Node elements are _usually_ empty and without attributes in xml
  328. //// so we don't make any of that type of convenience constructor here.
  329. // char* versions
  330. ConfigurationElement& Element( // Mapping factory for convenience,
  331. const char* Name, // requires a name, of course,
  332. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  333. ConfigurationElement& Element( // Mapping factory for convenience,
  334. const char* Name, // requires a name, of course,
  335. std::string& x, std::string init = std::string("")); // Map to a string.
  336. ConfigurationElement& Element( // Mapping factory for convenience,
  337. const char* Name, // requires a name, of course,
  338. int& x, int init = 0, int radix = 0); // Map to an int.
  339. ConfigurationElement& Element( // Mapping factory for convenience,
  340. const char* Name, // requires a name, of course,
  341. double& x, double init = 0.0); // Map to a double.
  342. ConfigurationElement& Element( // Mapping factory for convenience,
  343. const char* Name, // requires a name, of course,
  344. bool& x, bool init = false); // Map to a boolean.
  345. // string versions
  346. ConfigurationElement& Element( // Mapping factory for convenience,
  347. const std::string Name, // requires a name, of course,
  348. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  349. ConfigurationElement& Element( // Mapping factory for convenience,
  350. const std::string Name, // requires a name, of course,
  351. std::string& x, std::string init = std::string("")); // Map to a string.
  352. ConfigurationElement& Element( // Mapping factory for convenience,
  353. const std::string Name, // requires a name, of course,
  354. int& x, int init = 0, int radix = 0); // Map to an int.
  355. ConfigurationElement& Element( // Mapping factory for convenience,
  356. const std::string Name, // requires a name, of course,
  357. double& x, double init = 0.0); // Map to a double.
  358. ConfigurationElement& Element( // Mapping factory for convenience,
  359. const std::string Name, // requires a name, of course,
  360. bool& x, bool init = false); // Map to a boolean.
  361. // End methods for heading back up the tree at the end of an element.
  362. ConfigurationElement& End(); // Return this element's parent.
  363. ConfigurationElement& End(const char* Name); // Check the name and return the parent
  364. ConfigurationElement& End(const std::string Name); // if the name is correct - or throw!
  365. //// For adding new attributes to the parent element.
  366. ConfigurationAttribute& Attribute(const char* Name); // Add an attribute using a cstring.
  367. ConfigurationAttribute& Attribute(const std::string Name); // Add an attribute using a c++ string.
  368. //// Mapping Attribute factory methods for convenience.
  369. // char* versions
  370. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  371. const char* Name, // requires a name, of course,
  372. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  373. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  374. const char* Name, // requires a name, of course,
  375. std::string& x, std::string init = std::string("")); // Map to a string.
  376. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  377. const char* Name, // requires a name, of course,
  378. int& x, int init = 0, int radix = 0); // Map to an int.
  379. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  380. const char* Name, // requires a name, of course,
  381. double& x, double init = 0.0); // Map to a double.
  382. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  383. const char* Name, // requires a name, of course,
  384. bool& x, bool init = false); // Map to a boolean.
  385. // string versions
  386. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  387. const std::string Name, // requires a name, of course,
  388. ConfigurationTranslator& newTranslator); // Add a Translator to this element.
  389. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  390. const std::string Name, // requires a name, of course,
  391. std::string& x, std::string init = std::string("")); // Map to a string.
  392. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  393. const std::string Name, // requires a name, of course,
  394. int& x, int init = 0, int radix = 0); // Map to an int.
  395. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  396. const std::string Name, // requires a name, of course,
  397. double& x, double init = 0.0); // Map to a double.
  398. ConfigurationAttribute& Attribute( // Mapping factory for convenience,
  399. const std::string Name, // requires a name, of course,
  400. bool& x, bool init = false); // Map to a boolean.
  401. //// Set Init On Interprete for the parent element.
  402. ConfigurationElement& setInitOnInterpret(); // Set the init on interpret flag.
  403. //// For adding configurators to the parent element.
  404. ConfigurationElement& atStartCall(Configurator& Functor); // Add an atStart call-back to this element.
  405. ConfigurationElement& atEndCall(Configurator& Functor); // Add an atEnd call-back to this element.
  406. // Of course, the most useful thing about attributes is that they can
  407. // be mapped to variables using translators. The same as those that
  408. // apply to the parent element's contents. Here they are for use on this
  409. // attribute.
  410. ConfigurationAttribute& mapTo(ConfigurationTranslator& newTranslator); // Add a Translator to this attribute.
  411. ConfigurationAttribute& mapTo(std::string& x, std::string init = std::string("")); // Map to a string.
  412. ConfigurationAttribute& mapTo(int& x, int init, int radix = 0); // Map to an int.
  413. ConfigurationAttribute& mapTo(double& x, double init = 0.0); // Map to a double.
  414. ConfigurationAttribute& mapTo(bool& x, bool init = false); // Map to a boolean.
  415. // Attributes can have mnemonics just like elements.
  416. ConfigurationAttribute& Mnemonic(const char* name, const char* value); // Add a mnemonic using a c string.
  417. ConfigurationAttribute& Mnemonic(const char* name, const std::string value); // Add a mnemonic using c & c++ strings.
  418. ConfigurationAttribute& Mnemonic(const std::string name, const char* value); // Add a mnemonic using c++ & c strings.
  419. ConfigurationAttribute& Mnemonic(const std::string name, const std::string value); // Add a mnemonic using a c++ string.
  420. // Attributes participate in the Interprete() task just like elements.
  421. void initialize(); // Reset all translators to defaults.
  422. bool interpret(ConfigurationData& Data); // (re) Interpret this data.
  423. };
  424. //// Configuration Data ////////////////////////////////////////////////////////
  425. //
  426. // A ConfigurationData object holds on to the configuration source data and
  427. // provideds a place to log any information about how the configuration was
  428. // interpreted. It also creates and destroys a handy char[] to contain the
  429. // data. To make this beastie easier to handle, we use the Named Constructor
  430. // Idiom and hide the true constructor in the private section.
  431. class ConfigurationData { // Configuration Data Source
  432. private:
  433. char* myDataBuffer; // The actual data buffer.
  434. int myBufferSize; // Size of the current buffer.
  435. int myIndex; // The current interpretation index.
  436. int myLine; // Current line number.
  437. public:
  438. ConfigurationData(const char* FileName); // Constructor from c string file name.
  439. ConfigurationData(const std::string FileName); // Constructor from c++ string file name.
  440. ConfigurationData(const char* Data, int Length); // Raw constructor from text buffer.
  441. ~ConfigurationData(); // Destroys the internal buffer etc.
  442. char Data(int Index); // Returns char from Data[Index]
  443. int Index(); // Reads the current Index.
  444. int Index(int i); // Changes the current Index.
  445. int Line(); // Reads the current Line number.
  446. int addNewLines(int Count); // Increments the Line number.
  447. std::stringstream Log; // Convenient Interpret log.
  448. };
  449. //// Configuration Translator //////////////////////////////////////////////////
  450. //
  451. // A Translator converts the contents provided to it in string form into some
  452. // other data type. The object here is a prototype for that, followed by a
  453. // collection of the basic translators used for built-in mapTo()s.
  454. class ConfigurationTranslator { // Translators exist
  455. public:
  456. virtual ~ConfigurationTranslator(){}; // Stop No Virt Dtor warnings.
  457. virtual void translate(const char* Value) = 0; // Pure virtual translator.
  458. virtual void initialize() = 0; // Pure virtual initializer.
  459. };
  460. class StringTranslator : public ConfigurationTranslator {
  461. private:
  462. std::string& myVariable; // Variable to map.
  463. std::string myInitializer; // Initial/Default value.
  464. public:
  465. StringTranslator( // Construct this with
  466. std::string& Variable, // the variable to map,
  467. std::string Inititializer); // and the default value.
  468. void translate(const char* Value); // Provide a translation method.
  469. void initialize(); // Provide an initialization method.
  470. };
  471. class IntegerTranslator : public ConfigurationTranslator {
  472. private:
  473. int& myVariable; // Variable to map.
  474. int myInitializer; // Initial/Default value.
  475. int myRadix; // Radix for strtol()
  476. public:
  477. IntegerTranslator( // Construct this with
  478. int& Variable, // the variable to map,
  479. int Inititializer, // and the default value.
  480. int Radix); // For this one we also need a Radix.
  481. void translate(const char* Value); // Provide a translation method.
  482. void initialize(); // Provide an initialization method.
  483. };
  484. class DoubleTranslator : public ConfigurationTranslator {
  485. private:
  486. double& myVariable; // Variable to map.
  487. double myInitializer; // Initial/Default value.
  488. public:
  489. DoubleTranslator( // Construct this with
  490. double& Variable, // the variable to map,
  491. double Inititializer); // and the default value.
  492. void translate(const char* Value); // Provide a translation method.
  493. void initialize(); // Provide an initialization method.
  494. };
  495. class BoolTranslator : public ConfigurationTranslator {
  496. private:
  497. bool& myVariable; // Variable to map.
  498. bool myInitializer; // Initial/Default value.
  499. public:
  500. BoolTranslator( // Construct this with
  501. bool& Variable, // the variable to map,
  502. bool Inititializer); // and the default value.
  503. void translate(const char* Value); // Provide a translation method.
  504. void initialize(); // Provide an initialization method.
  505. };
  506. //// Configuration Mnemonic ////////////////////////////////////////////////////
  507. //
  508. // A Mnemonic allows the actual contents of an element or attribute to be
  509. // exchanged for a different "named" value to help eliminate "magic numbers"
  510. // and "secret codes" from configurations. One way this might be used is to
  511. // map an enumeration to the appropriate integer values, or things like YES and
  512. // NO to boolean true and false (respectively) when turning on/off program
  513. // options.
  514. class ConfigurationMnemonic { // Mnemonics
  515. private:
  516. std::string myName; // What is the Mnemonic?
  517. std::string myValue; // What is the translation?
  518. public:
  519. ConfigurationMnemonic(std::string Name, std::string Value); // To make one, provide both parts.
  520. bool test(std::string Name); // Test to see if this Mnemonic matches.
  521. std::string Value(); // If it does then we will need it's value.
  522. };
  523. //// Configurator //////////////////////////////////////////////////////////////
  524. //
  525. // A configurator is a "functor" or "closure" or "callback" that can be used to
  526. // support sophisticated interpretation options. The most basic and necessary
  527. // of these is support for list building. Consider an object created to contain
  528. // a list of records where each record might be represented as a collection of
  529. // attributes and elements. The object would have data elements mapped to the
  530. // attributes and elements in the configuration and then control elements which
  531. // are functors for initializing the list and storing new entries as they are
  532. // completed. The object here is a pure virtual prototype.
  533. class Configurator { // Configurators exist
  534. public:
  535. virtual void operator()(ConfigurationElement& E, ConfigurationData& D) = 0; // Pure virtual configurator.
  536. virtual ~Configurator() {} // Virtual dtor keeps warnings away.
  537. };
  538. //// Utilities /////////////////////////////////////////////////////////////////
  539. // SetTrueOnComplete Configurator //////////////////////////////////////////////
  540. class ConfiguratorSetTrueOnComplete : public Configurator { // Configurator set's a boolean true.
  541. private:
  542. bool* myBoolean; // The boolean to set.
  543. public:
  544. ConfiguratorSetTrueOnComplete(); // Must init to NULL for safety.
  545. void setup(bool& Target); // Link to the target boolean.
  546. void operator()(ConfigurationElement& E, ConfigurationData& D); // Handle the operation.
  547. };
  548. } // End namespace codedweller