src/FDM/JSBSim/input_output/FGXMLElement.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  File:         FGXMLElement.h
   4  Author:       Jon S. Berndt
   5  Date started: 9/28/04
   6
   7  ------------- Copyright (C) 2004  Jon S. Berndt (jon@jsbsim.org) -------------
   8
   9  This program is free software; you can redistribute it and/or modify it under
  10  the terms of the GNU Lesser General Public License as published by the Free Software
  11  Foundation; either version 2 of the License, or (at your option) any later
  12  version.
  13
  14  This program is distributed in the hope that it will be useful, but WITHOUT
  15  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  16  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  17  details.
  18
  19  You should have received a copy of the GNU Lesser General Public License along with
  20  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  21  Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23  Further information about the GNU Lesser General Public License can also be found on
  24  the world wide web at http://www.gnu.org.
  25
  26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  27 SENTRY
  28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  29
  30 #ifndef XMLELEMENT_H
  31 #define XMLELEMENT_H
  32
  33 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  34 INCLUDES
  35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  36
  37 #include <string>
  38 #include <map>
  39 #include <iostream>
  40 #include <vector>
  41
  42 using std::string;
  43 using std::map;
  44 using std::vector;
  45 using std::cout;
  46 using std::endl;
  47
  48 #include "math/FGColumnVector3.h"
  49
  50 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  51 DEFINITIONS
  52 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  53
  54 #define ID_XMLELEMENT "$Id$"
  55
  56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  57 FORWARD DECLARATIONS
  58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  59
  60 namespace JSBSim {
  61
  62 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  63 CLASS DOCUMENTATION
  64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  65
  66 /** Encapsulates an XML element.
  67     This class handles the creation, storage, and manipulation of XML elements.
  68     This class also can convert supplied values as follows:
  69
  70     convert ["from"]["to"] = factor, so: from * factor = to
  71     - convert["M"]["FT"] = 3.2808399;
  72     - convert["FT"]["M"] = 1.0/convert["M"]["FT"];
  73     - convert["M2"]["FT2"] = convert["M"]["FT"]*convert["M"]["FT"];
  74     - convert["FT2"]["M2"] = 1.0/convert["M2"]["FT2"];
  75     - convert["FT"]["IN"] = 12.0;
  76     - convert["IN"]["FT"] = 1.0/convert["FT"]["IN"];
  77     - convert["LBS"]["KG"] = 0.45359237;
  78     - convert["KG"]["LBS"] = 1.0/convert["LBS"]["KG"];
  79     - convert["SLUG*FT2"]["KG*M2"] = 1.35594;
  80     - convert["KG*M2"]["SLUG*FT2"] = 1.0/convert["SLUG*FT2"]["KG*M2"];
  81     - convert["RAD"]["DEG"] = 360.0/(2.0*3.1415926);
  82     - convert["DEG"]["RAD"] = 1.0/convert["RAD"]["DEG"];
  83     - convert["LBS/FT"]["N/M"] = 14.5939;
  84     - convert["LBS/FT/SEC"]["N/M/SEC"] = 14.5939;
  85     - convert["N/M"]["LBS/FT"] = 1.0/convert["LBS/FT"]["N/M"];
  86     - convert["N/M/SEC"]["LBS/FT/SEC"] = 1.0/convert["LBS/FT/SEC"]["N/M/SEC"];
  87     - convert["WATTS"]["HP"] = 0.001341022;
  88     - convert["HP"]["WATTS"] = 1.0/convert["WATTS"]["HP"];
  89     - convert["N"]["LBS"] = 0.22482;
  90     - convert["LBS"]["N"] = 1.0/convert["N"]["LBS"];
  91     - convert["KTS"]["FT/SEC"] = ktstofps;
  92     - convert["KG/MIN"]["LBS/MIN"] = convert["KG"]["LBS"];
  93     - convert["LBS/HP*HR"]["KG/KW*HR"] = 0.6083;
  94     - convert["KG/KW*HR"]["LBS/HP*HR"] = 1/convert["LBS/HP*HR"]["KG/KW*HR"];
  95     - convert["KG/L"]["LBS/GAL"] = 8.3454045;
  96
  97     - convert["M"]["M"] = 1.00;
  98     - convert["FT"]["FT"] = 1.00;
  99     - convert["IN"]["IN"] = 1.00;
 100     - convert["DEG"]["DEG"] = 1.00;
 101     - convert["RAD"]["RAD"] = 1.00;
 102     - convert["M2"]["M2"] = 1.00;
 103     - convert["FT2"]["FT2"] = 1.00;
 104     - convert["KG*M2"]["KG*M2"] = 1.00;
 105     - convert["SLUG*FT2"]["SLUG*FT2"] = 1.00;
 106     - convert["KG"]["KG"] = 1.00;
 107     - convert["LBS"]["LBS"] = 1.00;
 108     - convert["LBS/FT"]["LBS/FT"] = 1.00;
 109     - convert["N/M"]["N/M"] = 1.00;
 110     - convert["LBS/FT/SEC"]["LBS/FT/SEC"] = 1.00;
 111     - convert["N/M/SEC"]["N/M/SEC"] = 1.00;
 112     - convert["PSI"]["PSI"] = 1.00;
 113     - convert["INHG"]["INHG"] = 1.00;
 114     - convert["HP"]["HP"] = 1.00;
 115     - convert["N"]["N"] = 1.00;
 116     - convert["WATTS"]["WATTS"] = 1.00;
 117     - convert["KTS"]["KTS"] = 1.0;
 118     - convert["FT/SEC"]["FT/SEC"] = 1.0;
 119     - convert["KG/MIN"]["KG/MIN"] = 1.0;
 120     - convert["LBS/MIN"]["LBS/MIN"] = 1.0;
 121     - convert["LBS/HP*HR"]["LBS/HP*HR"] = 1.0;
 122     - convert["KG/KW*HR"]["KG/KW*HR"] = 1.0;
 123     - convert["KG/L"]["KG/L"] = 1.0;
 124     - convert["LBS/GAL"]["LBS/GAL"] = 1.0;
 125
 126     Where:
 127     - N = newtons
 128     - M = meters
 129     - M2 = meters squared
 130     - KG = kilograms
 131     - LBS = pounds force
 132     - FT = feet
 133     - FT2 = feet squared
 134     - SEC = seconds
 135     - MIN = minutes
 136     - SLUG = slug
 137     - DEG = degrees
 138     - RAD = radians
 139     - WATTS = watts
 140     - HP = horsepower
 141     - HR = hour
 142     - L = liter
 143     - GAL = gallon (U.S. liquid)
 144
 145     @author Jon S. Berndt
 146     @version $Id$
 147 */
 148
 149 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 150 CLASS DECLARATION
 151 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 152
 153 class Element {
 154 public:
 155   /** Constructor
 156       @param nm the name of this element (if given)
 157       */
 158   Element(string nm);
 159   /// Destructor
 160   ~Element(void);
 161
 162   /** Retrieves an attribute.
 163       @param key specifies the attribute key to retrieve the value of.
 164       @return the key value (as a string), or the empty string if no such
 165               attribute exists. */
 166   string GetAttributeValue(string key);
 167
 168   /** Retrieves an attribute value as a double precision real number.
 169       @param key specifies the attribute key to retrieve the value of.
 170       @return the key value (as a number), or the HUGE_VAL if no such
 171               attribute exists. */
 172   double GetAttributeValueAsNumber(string key);
 173
 174   /** Retrieves the element name.
 175       @return the element name, or the empty string if no name has been set.*/
 176   string GetName(void) {return name;}
 177
 178   /** Gets a line of data belonging to an element.
 179       @param i the index of the data line to return (0 by default).
 180       @return a string representing the data line requested, or the empty string
 181               if none exists.*/
 182   string GetDataLine(unsigned int i=0);
 183
 184   /// Returns the number of lines of data stored
 185   unsigned int GetNumDataLines(void) {return (unsigned int)data_lines.size();}
 186
 187   /// Returns the number of child elements for this element.
 188   unsigned int GetNumElements(void) {return (unsigned int)children.size();}
 189
 190   /// Returns the number of named child elements for this element.
 191   unsigned int GetNumElements(string);
 192
 193   /** Converts the element data to a number.
 194       This function attempts to convert the first (and presumably only) line of
 195       data "owned" by the element into a real number. If there is not exactly one
 196       line of data owned by the element, then HUGE_VAL is returned.
 197       @return the numeric value of the data owned by the element.*/
 198   double GetDataAsNumber(void);
 199
 200   /** Returns a pointer to the element requested by index.
 201       This function also resets an internal counter to the index, so that
 202       subsequent calls to GetNextElement() will return the following
 203       elements sequentially, until the last element is reached. At that point,
 204       GetNextElement() will return NULL.
 205       @param el the index of the requested element (0 by default)
 206       @return a pointer to the Element, or 0 if no valid element exists. */
 207   Element* GetElement(unsigned int el=0);
 208
 209   /** Returns a pointer to the next element in the list.
 210       The function GetElement() must be called first to be sure that this
 211       function will return the correct element. The call to GetElement() resets
 212       the internal counter to zero. Subsequent calls to GetNextElement() return
 213       a pointer to subsequent elements in the list. When the final element is
 214       reached, 0 is returned.
 215       @return a pointer to the next Element in the sequence, or 0 if no valid
 216               Element is present. */
 217   Element* GetNextElement(void);
 218
 219   /** Returns a pointer to the parent of an element.
 220       @return a pointer to the parent Element, or 0 if this is the top level Element. */
 221   Element* GetParent(void) {return parent;}
 222
 223   /** Searches for a specified element.
 224       Finds the first element that matches the supplied string, or simply the first
 225       element if no search string is supplied. This function call resets the internal
 226       element counter to the first element.
 227       @param el the search string (empty string by default).
 228       @return a pointer to the first element that matches the supplied search string. */
 229   Element* FindElement(string el="");
 230
 231   /** Searches for the next element as specified.
 232       This function would be called after FindElement() is first called (in order to
 233       reset the internal counter). If no argument is supplied (or the empty string)
 234       a pointer to the very next element is returned. Otherwise, the next occurence
 235       of the named element is returned. If the end of the list is reached, 0 is
 236       returned.
 237       @param el the name of the next element to find.
 238       @return the pointer to the found element, or 0 if no appropriate element us
 239               found.*/
 240   Element* FindNextElement(string el="");
 241
 242   /** Searches for the named element and returns the string data belonging to it.
 243       This function allows the data belonging to a named element to be returned
 244       as a string. If no element is found, the empty string is returned. If no
 245       argument is supplied, the data string for the first element is returned.
 246       @param el the name of the element being searched for (the empty string by
 247       default)
 248       @return the data value for the named element as a string, or the empty
 249               string if the element cannot be found. */
 250   string FindElementValue(string el="");
 251
 252   /** Searches for the named element and returns the data belonging to it as a number.
 253       This function allows the data belonging to a named element to be returned
 254       as a double. If no element is found, HUGE_VAL is returned. If no
 255       argument is supplied, the data for the first element is returned.
 256       @param el the name of the element being searched for (the empty string by
 257       default)
 258       @return the data value for the named element as a double, or HUGE_VAL if the
 259               data is missing. */
 260   double FindElementValueAsNumber(string el="");
 261
 262   /** Searches for the named element and converts and returns the data belonging to it.
 263       This function allows the data belonging to a named element to be returned
 264       as a double. If no element is found, HUGE_VAL is returned. If no
 265       argument is supplied, the data for the first element is returned. Additionally,
 266       this function converts the value from the units specified in the config file (via
 267       the UNITS="" attribute in the element definition) to the native units used by
 268       JSBSim itself, as specified by the target_units parameter. The currently
 269       allowable unit conversions are seen in the source file FGXMLElement.cpp.
 270       Also, see above in the main documentation for this class.
 271       @param el the name of the element being searched for (the empty string by
 272       default)
 273       @param target_units the string representing the native units used by JSBSim
 274              to which the value returned will be converted.
 275       @return the unit-converted data value for the named element as a double,
 276               or HUGE_VAL if the data is missing. */
 277   double FindElementValueAsNumberConvertTo(string el, string target_units);
 278
 279   /** Searches for the named element and converts and returns the data belonging to it.
 280       This function allows the data belonging to a named element to be returned
 281       as a double. If no element is found, HUGE_VAL is returned. If no
 282       argument is supplied, the data for the first element is returned. Additionally,
 283       this function converts the value from the units specified in the supplied_units
 284       parameter to the units specified in the target_units parameter. JSBSim itself,
 285       as specified by the target_units parameter. The currently allowable unit
 286       conversions are seen in the source file FGXMLElement.cpp. Also, see above
 287       in the main documentation for this class.
 288       @param el the name of the element being searched for (the empty string by
 289       default)
 290       @param supplied_units the string representing the units of the value as
 291              supplied by the config file.
 292       @param target_units the string representing the native units used by JSBSim
 293              to which the value returned will be converted.
 294       @return the unit-converted data value for the named element as a double,
 295               or HUGE_VAL if the data is missing. */
 296   double FindElementValueAsNumberConvertFromTo( string el,
 297                                                 string supplied_units,
 298                                                 string target_units);
 299
 300   /** Composes a 3-element column vector for the supplied location or orientation.
 301       This function processes a LOCATION or ORIENTATION construct, returning a
 302       filled-out 3-element column vector containing the X, Y, Z or ROLL, PITCH,
 303       YAW elements found in the supplied element. If one of the mentioned components
 304       is not found, that component is set to zero and a warning message is printed.
 305       All three elements should be supplied.
 306       @param target_units the string representing the native units used by JSBSim
 307              to which the value returned will be converted.
 308       @return a column vector object built from the LOCATION or ORIENT components. */
 309   FGColumnVector3 FindElementTripletConvertTo( string target_units);
 310
 311   /** This function sets the value of the parent class attribute to the supplied
 312       Element pointer.
 313       @param p pointer to the parent Element. */
 314   void SetParent(Element* p) {parent = p;}
 315
 316   /** Adds a child element to the list of children stored for this element.
 317   *   @param el Child element to add. */
 318   void AddChildElement(Element* el) {children.push_back(el);}
 319
 320   /** Stores an attribute belonging to this element.
 321   *   @param name The string name of the attribute.
 322   *   @param value The string value of the attribute. */
 323   void AddAttribute(string name, string value);
 324
 325   /** Stores data belonging to this element.
 326   *   @param d the data to store. */
 327   void AddData(string d);
 328
 329   /** Prints the element.
 330   *   Prints this element and calls the Print routine for child elements.
 331   *   @param d The tab level. A level corresponds to a single space. */
 332   void Print(unsigned int level=0);
 333
 334 private:
 335   string name;
 336   map <string, string> attributes;
 337   vector <string> data_lines;
 338   vector <Element*> children;
 339   vector <string> attribute_key;
 340   Element *parent;
 341   unsigned int element_index;
 342   typedef map <string, map <string, double> > tMapConvert;
 343   static tMapConvert convert;
 344   static bool converterIsInitialized;
 345 };
 346
 347 } // namespace JSBSim
 348
 349 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 350
 351 #endif