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 (jsb@hal-pc.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
  96     - convert["M"]["M"] = 1.00;
  97     - convert["FT"]["FT"] = 1.00;
  98     - convert["IN"]["IN"] = 1.00;
  99     - convert["DEG"]["DEG"] = 1.00;
 100     - convert["RAD"]["RAD"] = 1.00;
 101     - convert["M2"]["M2"] = 1.00;
 102     - convert["FT2"]["FT2"] = 1.00;
 103     - convert["KG*M2"]["KG*M2"] = 1.00;
 104     - convert["SLUG*FT2"]["SLUG*FT2"] = 1.00;
 105     - convert["KG"]["KG"] = 1.00;
 106     - convert["LBS"]["LBS"] = 1.00;
 107     - convert["LBS/FT"]["LBS/FT"] = 1.00;
 108     - convert["N/M"]["N/M"] = 1.00;
 109     - convert["LBS/FT/SEC"]["LBS/FT/SEC"] = 1.00;
 110     - convert["N/M/SEC"]["N/M/SEC"] = 1.00;
 111     - convert["PSI"]["PSI"] = 1.00;
 112     - convert["INHG"]["INHG"] = 1.00;
 113     - convert["HP"]["HP"] = 1.00;
 114     - convert["N"]["N"] = 1.00;
 115     - convert["WATTS"]["WATTS"] = 1.00;
 116     - convert["KTS"]["KTS"] = 1.0;
 117     - convert["FT/SEC"]["FT/SEC"] = 1.0;
 118     - convert["KG/MIN"]["KG/MIN"] = 1.0;
 119     - convert["LBS/MIN"]["LBS/MIN"] = 1.0;
 120     - convert["LBS/HP*HR"]["LBS/HP*HR"] = 1.0;
 121     - convert["KG/KW*HR"]["KG/KW*HR"] = 1.0;
 122
 123     Where:
 124     - N = newtons
 125     - M = meters
 126     - M2 = meters squared
 127     - KG = kilograms
 128     - LBS = pounds force
 129     - FT = feet
 130     - FT2 = feet squared
 131     - SEC = seconds
 132     - MIN = minutes
 133     - SLUG = slug
 134     - DEG = degrees
 135     - RAD = radians
 136     - WATTS = watts
 137     - HP = horsepower
 138     - HR = hour
 139
 140     @author Jon S. Berndt
 141     @version $Id$
 142 */
 143
 144 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 145 CLASS DECLARATION
 146 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 147
 148 class Element {
 149 public:
 150   /** Constructor
 151       @param nm the name of this element (if given)
 152       */
 153   Element(string nm);
 154   /// Destructor
 155   ~Element(void);
 156
 157   /** Retrieves an attribute.
 158       @param key specifies the attribute key to retrieve the value of.
 159       @return the key value (as a string), or the empty string if no such
 160               attribute exists. */
 161   string GetAttributeValue(string key);
 162
 163   /** Retrieves an attribute value as a double precision real number.
 164       @param key specifies the attribute key to retrieve the value of.
 165       @return the key value (as a number), or the HUGE_VAL if no such
 166               attribute exists. */
 167   double GetAttributeValueAsNumber(string key);
 168
 169   /** Retrieves the element name.
 170       @return the element name, or the empty string if no name has been set.*/
 171   string GetName(void) {return name;}
 172
 173   /** Gets a line of data belonging to an element.
 174       @param i the index of the data line to return (0 by default).
 175       @return a string representing the data line requested, or the empty string
 176               if none exists.*/
 177   string GetDataLine(unsigned int i=0);
 178
 179   /// Returns the number of lines of data stored
 180   unsigned int GetNumDataLines(void) {return (unsigned int)data_lines.size();}
 181
 182   /// Returns the number of child elements for this element.
 183   unsigned int GetNumElements(void) {return (unsigned int)children.size();}
 184
 185   /// Returns the number of named child elements for this element.
 186   unsigned int GetNumElements(string);
 187
 188   /** Converts the element data to a number.
 189       This function attempts to convert the first (and presumably only) line of
 190       data "owned" by the element into a real number. If there is not exactly one
 191       line of data owned by the element, then HUGE_VAL is returned.
 192       @return the numeric value of the data owned by the element.*/
 193   double GetDataAsNumber(void);
 194
 195   /** Returns a pointer to the element requested by index.
 196       This function also resets an internal counter to the index, so that
 197       subsequent calls to GetNextElement() will return the following
 198       elements sequentially, until the last element is reached. At that point,
 199       GetNextElement() will return NULL.
 200       @param el the index of the requested element (0 by default)
 201       @return a pointer to the Element, or 0 if no valid element exists. */
 202   Element* GetElement(unsigned int el=0);
 203
 204   /** Returns a pointer to the next element in the list.
 205       The function GetElement() must be called first to be sure that this
 206       function will return the correct element. The call to GetElement() resets
 207       the internal counter to zero. Subsequent calls to GetNextElement() return
 208       a pointer to subsequent elements in the list. When the final element is
 209       reached, 0 is returned.
 210       @return a pointer to the next Element in the sequence, or 0 if no valid
 211               Element is present. */
 212   Element* GetNextElement(void);
 213
 214   /** Returns a pointer to the parent of an element.
 215       @return a pointer to the parent Element, or 0 if this is the top level Element. */
 216   Element* GetParent(void) {return parent;}
 217
 218   /** Searches for a specified element.
 219       Finds the first element that matches the supplied string, or simply the first
 220       element if no search string is supplied. This function call resets the internal
 221       element counter to the first element.
 222       @param el the search string (empty string by default).
 223       @return a pointer to the first element that matches the supplied search string. */
 224   Element* FindElement(string el="");
 225
 226   /** Searches for the next element as specified.
 227       This function would be called after FindElement() is first called (in order to
 228       reset the internal counter). If no argument is supplied (or the empty string)
 229       a pointer to the very next element is returned. Otherwise, the next occurence
 230       of the named element is returned. If the end of the list is reached, 0 is
 231       returned.
 232       @param el the name of the next element to find.
 233       @return the pointer to the found element, or 0 if no appropriate element us
 234               found.*/
 235   Element* FindNextElement(string el="");
 236
 237   /** Searches for the named element and returns the string data belonging to it.
 238       This function allows the data belonging to a named element to be returned
 239       as a string. If no element is found, the empty string is returned. If no
 240       argument is supplied, the data string for the first element is returned.
 241       @param el the name of the element being searched for (the empty string by
 242       default)
 243       @return the data value for the named element as a string, or the empty
 244               string if the element cannot be found. */
 245   string FindElementValue(string el="");
 246
 247   /** Searches for the named element and returns the data belonging to it as a number.
 248       This function allows the data belonging to a named element to be returned
 249       as a double. If no element is found, HUGE_VAL is returned. If no
 250       argument is supplied, the data for the first element is returned.
 251       @param el the name of the element being searched for (the empty string by
 252       default)
 253       @return the data value for the named element as a double, or HUGE_VAL if the
 254               data is missing. */
 255   double FindElementValueAsNumber(string el="");
 256
 257   /** Searches for the named element and converts and returns the data belonging to it.
 258       This function allows the data belonging to a named element to be returned
 259       as a double. If no element is found, HUGE_VAL is returned. If no
 260       argument is supplied, the data for the first element is returned. Additionally,
 261       this function converts the value from the units specified in the config file (via
 262       the UNITS="" attribute in the element definition) to the native units used by
 263       JSBSim itself, as specified by the target_units parameter. The currently
 264       allowable unit conversions are seen in the source file FGXMLElement.cpp.
 265       Also, see above in the main documentation for this class.
 266       @param el the name of the element being searched for (the empty string by
 267       default)
 268       @param target_units the string representing the native units used by JSBSim
 269              to which the value returned will be converted.
 270       @return the unit-converted data value for the named element as a double,
 271               or HUGE_VAL if the data is missing. */
 272   double FindElementValueAsNumberConvertTo(string el, string target_units);
 273
 274   /** Searches for the named element and converts and returns the data belonging to it.
 275       This function allows the data belonging to a named element to be returned
 276       as a double. If no element is found, HUGE_VAL is returned. If no
 277       argument is supplied, the data for the first element is returned. Additionally,
 278       this function converts the value from the units specified in the supplied_units
 279       parameter to the units specified in the target_units parameter. JSBSim itself,
 280       as specified by the target_units parameter. The currently allowable unit
 281       conversions are seen in the source file FGXMLElement.cpp. Also, see above
 282       in the main documentation for this class.
 283       @param el the name of the element being searched for (the empty string by
 284       default)
 285       @param supplied_units the string representing the units of the value as
 286              supplied by the config file.
 287       @param target_units the string representing the native units used by JSBSim
 288              to which the value returned will be converted.
 289       @return the unit-converted data value for the named element as a double,
 290               or HUGE_VAL if the data is missing. */
 291   double FindElementValueAsNumberConvertFromTo( string el,
 292                                                 string supplied_units,
 293                                                 string target_units);
 294
 295   /** Composes a 3-element column vector for the supplied location or orientation.
 296       This function processes a LOCATION or ORIENTATION construct, returning a
 297       filled-out 3-element column vector containing the X, Y, Z or ROLL, PITCH,
 298       YAW elements found in the supplied element. If one of the mentioned components
 299       is not found, that component is set to zero and a warning message is printed.
 300       All three elements should be supplied.
 301       @param target_units the string representing the native units used by JSBSim
 302              to which the value returned will be converted.
 303       @return a column vector object built from the LOCATION or ORIENT components. */
 304   FGColumnVector3 FindElementTripletConvertTo( string target_units);
 305
 306   /** This function sets the value of the parent class attribute to the supplied
 307       Element pointer.
 308       @param p pointer to the parent Element. */
 309   void SetParent(Element* p) {parent = p;}
 310
 311   /** Adds a child element to the list of children stored for this element.
 312   *   @param el Child element to add. */
 313   void AddChildElement(Element* el) {children.push_back(el);}
 314
 315   /** Stores an attribute belonging to this element.
 316   *   @param name The string name of the attribute.
 317   *   @param value The string value of the attribute. */
 318   void AddAttribute(string name, string value);
 319
 320   /** Stores data belonging to this element.
 321   *   @param d the data to store. */
 322   void AddData(string d);
 323
 324   /** Prints the element.
 325   *   Prints this element and calls the Print routine for child elements.
 326   *   @param d The tab level. A level corresponds to a single space. */
 327   void Print(unsigned int level=0);
 328
 329 private:
 330   string name;
 331   map <string, string> attributes;
 332   vector <string> data_lines;
 333   vector <Element*> children;
 334   vector <string> attribute_key;
 335   Element *parent;
 336   unsigned int element_index;
 337   typedef map <string, map <string, double> > tMapConvert;
 338   tMapConvert convert;
 339 };
 340
 341 } // namespace JSBSim
 342
 343 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 344
 345 #endif