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