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